What sort of documentation? Documentation can be provided for a number of different purposes, and what is useful/acceptable/desirable in one situation may not apply equally in others.

Also, what language are you using? Whilst most general preferences of documentation should be largely language agnostic, some languages tend to use certain styles which it may behove you to stick to, and you may get certain tool recommendations based on your choice of language...
[/quote]

C++

For a low level API documentation something automatically generated based on the code and comments with a tool such as JavaDoc or DoxyGen is normally suitable; the automatic generation helps reduce the workload and ensure documentation is complete, and should also make it easier to ensure your documents are kept up-to-date with changes. This documentation should be as complete as possible and would normally be intended for your own usage or for those who might be making modifications to or porting your code. Unless your code is very simple automatically generated documentation probably isn't the best resource for consumers/users of your code.
[/quote]

Glad you threw that last sentence in there. I don't think automatically generated docs are going to be a key part of the solution.

For your public interface I prefer a complete reference which might be built on top of automatically generated documentation or could be hand-written but which should include additional information on the intended usage of your code as well as minimal but complete examples of usage; any included examples should either compile or should mention any inclusions or dependencies to make them work.


You might also have documentation for people to familiarise themselves with your code. This could come in the form of:

• Some simple examples of common or intended usage, ideally with a brief explanation of the flow and decisions behind the code structure.
  
• Tutorials aimed at getting beginner users and/or users of similar code started working with your code.
  
• An overview document listing what your code is intended to be used for and why it might be a better choice than common alternatives.
  

In general, I like documentation to be:

1. Complete for the purpose they are intended for. i.e. it's fine for documentation to only list the public interface if you are not intending to provide a complete API reference, but if parts of the public interface are not included at all your documentation should be updated to fix this. Any intentional omissions for the purpose of brevity (example: it's common to leave error checking out of samples) should be noted in the documentation.
   
2. Concise. Whilst documentation should include all the necessary information, it shouldn't ramble on, repeat itself or include additional un-needed information unless there's some good reason for doing so. I normally take a couple of passes at writing my documentation and try to cut it down to as minimal as possible whilst still serving it's purpose.
   
3. Current. Documentation that isn't kept up-to-date, doesn't include information on new additions, or has become incorrect due to not being updated after changes can be worse than no documentation at all.
   
4. Readily available. It should be clear what documentation is available for your code, and where I can find it. The best user manual in the world is no use if it's hidden away on your website with no clear links to it and no mention anywhere that I might want to look for it.
   

This is all of course just personal preferences and opinions, but I hope that helps!
[/quote]


Thanks. It does.

[quote name='wood_brian' timestamp='1326254246' post='4901520']
I kind of want to go more into integrating documentation on my site. These pages
http://webEbenezer.n...retedTypes.html
http://webEbenezer.n...ntegration.html and the examples on the site are documentation related, but it seems things aren't as cohesive as they could be.

• You start by mentioning that you offer free services, and that the main one is your C++ Middleware Writer; quickly looking around your site, there don't actually seem to be any other services on offer. I would either simply make the page all about the CMW, or give the CMW it's own page so that it isn't sharing space with these ill-defined "other services". Your page then has a clearer focus and users aren't distracted by the potential of "other services" or the worry that something might not relate to the CMW.
  
• A simple website is fine (and often even preferable), but you would probably benefit from at least some basic page layout rather than everything simply being listed top-to-bottom. You could have a simple menu -- nothing fancy is required, it can still just be text links -- either along the top of the page, or down the left-hand side which appears on every page and has items such as "home", "documentation", "links", etc. You should probably also set up a separate "download" page, as it isn't presently clear exactly how one goes about obtaining your library without doing some digging through the content.
  
• Remove irrelevant content. The link "A voice of reason in the Democratic Party?" on your homepage has nothing to do with either the CMW or your consulting services, and if you want to attract users you should remove unrelated content, or at least tuck it away on the links page or move it to a personal blog.
  

• Your homepage is the place to introduce your product. You should write a short and concise introduction to what your library actually does, and why people might want to use it. It probably shouldn't be longer than 3-4 paragraphs with a few sentences each, but something more detailed than what the page currently starts with would probably be beneficial. Your introduction should also point people in the direction of both your documentation and the download page so that potential new users have a clear flow of where to go next. Your new developments can then follow on after the introduction where they're not in the way of a new user who may not be interested in them.
  

Next, I suggested you should add a specific top-level page for documentation. This page should link to your other documentation, which should ideally include some sort of tutorial on getting started -- this would be built off your existing page on build integration, but should take a more hand-holding approach of walking users through initial setup, and should also include a simple and minimal piece of code that users can run to assess whether they have set up your library correctly. You should also have on their own pages a more detailed reference on how to use your library (which need not take such a hand-holding approach), and a page of examples/sample usages. You should also have a brief write-up somewhere of why using your library is better than alternatives -- you might give this it's own page in the documentation, or you might include it on the top-level documentation page. You could also consider including an faq, although I would advise against doing so until such time as you actually receive questions from users.

You should also provide a licence (even if it's just that you're releasing the code into the public domain) for your library somewhere prominent on the site -- I don't currently see anything of the sort, and this is something experienced developers will usually want to check before considering using a new library.


Does that help?
[/quote]
I'm trying to document what I call Middle code and Middle files.
---------------------------------------------------------------------------------------

Lines with the following general form are the basis of Middle code:
[ @out @in ] (T1, T2, ... Tn)

Options start with an @ symbol. @out and @in are used to control the output. If you specify neither, both input and output code will be created. Specify just @in or just @out to tailor the output from the C++ Middleware Writer (CMW). After any options, a list of C++ types is enclosed in a set of parentheses. One or more of these lines are wrapped by a name and a closing brace -- } -- like this:

local_messages_front
@out (marshalling_integer, const char*, const char*, int64_t)

@in (bool)
@in (std::string)
}


Based on that input, the CMW creates a local_messages_front class in two files: local_messages_front.cg.hh and local_messages_front.cg.cc.

To comment out some Middle code, use // as usual.

-------------------------------------------------------------------------------------------
I haven't mentioned anything about files yet and need to say something about how it's OK to put multiple constructs into one Middle file:


local_messages_middle
@in (cmw_request)

@out (bool)
@out (bool, const char*)
}

local_messages_front
@out (marshalling_integer, const char*, const char*, int64_t)

@in (bool)
@in (std::string)
}


My middle tier uses the local_messages_middle class to communicate with the front tier and the front tier uses local_messages_front to communicate with the middle tier. I don't have a name for these (two) constructs. They are the high-level descriptions of the classes/messages I plan to use. It probably only makes sense to put two of these constructs in one Middle file, but it is possible to put more than that. (These two constructs mirror each other even though it is a little hard to tell from this. The cmw_request consists of a marshalling_integer, two strings and an int64_t. I don't use cmw_request in the front tier because it would take time to construct it and then I wouldn't use it for anything other than marshalling. Similarly, the middle tier doesn't construct a string from an exception's what value just to marshal it.)