Jump to content
  • Advertisement
Sign in to follow this  
wood_brian

Documentation tips and links

This topic is 2526 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

I'm reworking my documentation. What do you like about your documentation? What don't you like about it? ...
Tia.

Brian Wood
Ebenezer Enterprises
http://webEbenezer.net

Share this post


Link to post
Share on other sites
Advertisement
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...


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.


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.


    Lastly, your comments within the code are documentation. Where possible, you should ideally prefer clear, "self-documenting" code to providing an explanation via comments. Unless you've done something unusual or particularly complex (which you should only do with good reason!), you should not have to make comments explaining what the code is doing, but should instead reserve them for explaining why certain decisions were made. Obviously this doesn't apply to comments included for the purpose of helping out auto-documenting tools such as Doxygen, but most such tools are able to be configured in such a way that you can include any comments required for them to work effectively outside of your code files; I strongly prefer doing so to avoid clutter amongst the code itself.


    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! smile.png

Share this post


Link to post
Share on other sites
Self-documenting code.

Obviously it's not possible 100% of the time, and doesn't serve to fully replace traditional documentation, but if you are investing time in writing documentation, it's worth investing a little time in cleaning up your public API.

Make sure function/class names match their typical use-case (maybe different from their intended use). Provide unit tests and/or error checking for common edge-cases. Try and make sure that the behaviour of functions/classes doesn't depend on 3rd-party state...

Share this post


Link to post
Share on other sites

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.

To help people learn how to use the software. I have a 3-tier system. Two of the tiers are open-source and have to be built and run by users. All of the tiers link to a library.


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.

    Lastly, your comments within the code are documentation. Where possible, you should ideally prefer clear, "self-documenting" code to providing an explanation via comments. Unless you've done something unusual or particularly complex (which you should only do with good reason!), you should not have to make comments explaining what the code is doing, but should instead reserve them for explaining why certain decisions were made. Obviously this doesn't apply to comments included for the purpose of helping out auto-documenting tools such as Doxygen, but most such tools are able to be configured in such a way that you can include any comments required for them to work effectively outside of your code files; I strongly prefer doing so to avoid clutter amongst the code itself.
    [/quote]

    I'm a believer in the "self-documenting" approach, but am mainly interested in the more traditional aspects of documentation here.
    I kind of want to go more into integrating documentation on my site. These pages
    http://webEbenezer.n...rtedTypes.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.


    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! smile.png
    [/quote]


    Thanks. It does.

Share this post


Link to post
Share on other sites

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.

It seems like you probably need more structure to the information -- what you have there at the moment seems a bit like bits and pieces of information have simply been added as you've thought of them or as users have asked questions, with no regard for order or flow -- this works alright if you know where the information is and have a basic familiarity with the library, but it's not very approachable for a new user.

To be honest, the whole website is both very basic and largely unstructured, and probably not well suited to either attracting or aiding new users. I would probably start by cleaning up and reorganising what you already have, and then adding new information to fill the gaps.


Starting with your homepage:

  • 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?

Share this post


Link to post
Share on other sites
Going along with what JBAdams said, I opened your page and was completely confused to what you actually offered.

If I didn't see this thread my impression would be that it was a miminalist-format developer blog.


When in doubt, look at what the best ones do and learn from it.

Microsoft's MSDN Library is one of the foremost documentation sites for developer docs. Open your blog-style home page, then look at the MSDN Library home page. It has one paragraph of text for those who don't know what is going on, with a link for more details. Then it has three links for each technology: technology overview, API reference, samples/walkthroughs.

That is EXACTLY what I want as a developer. When I need developer documentation, I'm there for one of three purposes:
(1) I want to look at an overview of the technology to see what it can do for me, what functionality it has and does not have and make decisions quickly.
(2) I want to see an example of the end-to-end use. I want to see clean samples that show exactly how I get the results described in #1 above.
(3) I want to see a reference on a specific function. I want to get answer to what it does, what it returns, and what side effects it has. This is to drill deeper into the details of #2 above.



Figure out the purpose of the site. Are you selling something? If so then make it look like a slick glossy brochure. Are you there to support programmers? If so then give exactly the information they need. Are you doing both? You can't do both effectively in a single site; make them separate, keep the sales brochure as your main site since that's where you get your money, then provide a single link on the home page to the developer section.

I'd much rather see the main WebEbenizer.net as the sales side, developers.WebEbinizer.net as the documentation side. Keep them as distinct logical units.

Share this post


Link to post
Share on other sites
To provide a couple of additional examples:

SDL is a popular library. The official site has a menu down the left side with categorized links to anything you might want to find. The homepage has a clear and concise explanation of what the library does, a list of supported platforms, and lists the licence the library is provided under.

SFML is a newer alternative to SDL that is becoming increasingly popular. Again, the site has a menu down the left side with links to each section. The homepage starts with a brief description and includes links to "find out more", "download" binaries or source code, or to contact the author. There's also a nice big graphical download button prominently displayed.


Provide a simple layout with a clear logical structure, and make sure whatever your user might be looking for is readily accessible. smile.png

Share this post


Link to post
Share on other sites

[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.



Starting with your homepage:

  • 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.

      [/quote]

      I've made changes related to your first bullet.


      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.)

Share this post


Link to post
Share on other sites
In descending order of usefulness and tendency to be maintained and remain correct: self documenting code, BDD style tests, usage examples, naive TDD style tests, descriptive text in a document, comments.

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

GameDev.net is your game development community. Create an account for your GameDev Portfolio and participate in the largest developer community in the games industry.

Sign me up!