Difference between revisions of "Software Documentation"
Jump to navigation
Jump to search
↑ https://civicrm.org/blog/michael-mcandrew/a-new-home-for-our-documentation
m (link to new article) |
(Adds examples of what the CiviCRM and Drupal project are using) |
||
| (One intermediate revision by the same user not shown) | |||
| Line 12: | Line 12: | ||
## installing the software | ## installing the software | ||
## using the software in the most common use-cases with examples, illustrations, or videos | ## using the software in the most common use-cases with examples, illustrations, or videos | ||
| − | ### On this last point, a special name for the "User Manual", especially when integrated into the user interface of the software, is "Help". Because systems may be aggregates of several pieces of software, there is often a need for "Help" that addresses how the underlying software is aggregated into that particular system. A perfect example is a wiki (like this one) that includes many 'extensions' to provide specific functionality in addition to what the core software does; and local . | + | ### On this last point, a special name for the "User Manual", especially when integrated into the user interface of the software, is "Help". Because systems may be aggregates of several pieces of software, there is often a need for "Help" that addresses how the underlying software is aggregated into that particular system. A perfect example is a wiki (like this one) that includes many 'extensions' to provide specific functionality in addition to what the core software does; and local [[Category:Help|Help]]. |
# "API Docs" is a special nuance of Documentation. If your software includes an [[API]], then that API needs to be fully documented almost as a separate piece of software -- for both developers of the API and users of the API. | # "API Docs" is a special nuance of Documentation. If your software includes an [[API]], then that API needs to be fully documented almost as a separate piece of software -- for both developers of the API and users of the API. | ||
| Line 26: | Line 26: | ||
The PyDoc tool is used to generate documentation on the language itself, and is also leveraged as a framework for developers of help systems and obviously used to document any classes, and methods of source code. | The PyDoc tool is used to generate documentation on the language itself, and is also leveraged as a framework for developers of help systems and obviously used to document any classes, and methods of source code. | ||
| − | The [[CiviCRM]] project, which originally used the Atlassian Confluence Wiki product for documentation, moved over to the (better) '''Read The Docs''' system<ref>https://civicrm.org/blog/michael-mcandrew/a-new-home-for-our-documentation</ref> (based on markdown) in a [https://github.com/civicrm/civicrm-user-guide github repository] and uses the [http://www.mkdocs.org/ MkDocs] (BSD) | + | The [[CiviCRM]] project, which originally used the Atlassian Confluence Wiki product for documentation, moved over to the (better) '''Read The Docs''' system<ref>https://civicrm.org/blog/michael-mcandrew/a-new-home-for-our-documentation</ref> (based on markdown) in a [https://github.com/civicrm/civicrm-user-guide github repository] and uses the [http://www.mkdocs.org/ MkDocs] (BSD) static site generator tool to publish to their own domain http://docs.civicrm.org/user/en/4.6/ |
Meanwhile, the [[Drupal]] project has a [https://www.drupal.org/governance/doc-working-group Documentation Working Group] who is using [http://www.methods.co.nz/asciidoc/ AsciiDoc] (GPL) to do the [https://www.drupal.org/project/user_guide User Guide] documentation for Drupal 8 | Meanwhile, the [[Drupal]] project has a [https://www.drupal.org/governance/doc-working-group Documentation Working Group] who is using [http://www.methods.co.nz/asciidoc/ AsciiDoc] (GPL) to do the [https://www.drupal.org/project/user_guide User Guide] documentation for Drupal 8 | ||
| Line 32: | Line 32: | ||
== Documenting PHP Code == | == Documenting PHP Code == | ||
The main resource is the [http://www.phpdoc.org Project website], including tutorials and full Documentation. The system can be installed via the PEAR installer, but should not be setup in an Internet-facing environment. See the [[PhpDocumentor]] article for details on our installation and usage. | The main resource is the [http://www.phpdoc.org Project website], including tutorials and full Documentation. The system can be installed via the PEAR installer, but should not be setup in an Internet-facing environment. See the [[PhpDocumentor]] article for details on our installation and usage. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
== Documenting other languages == | == Documenting other languages == | ||
| Line 56: | Line 49: | ||
* http://www.open-emr.org/wiki/index.php/How_to_Document_Your_Code_Properly | * http://www.open-emr.org/wiki/index.php/How_to_Document_Your_Code_Properly | ||
| − | |||
| − | |||
| − | |||
[[Category:Applications]] | [[Category:Applications]] | ||
[[Category:Help]] | [[Category:Help]] | ||
Revision as of 10:16, 1 June 2016
There are different types of documentation for software:
- "Developer Docs" is the documentation of the code, targeted at developers, to explain what the code does and how it does it so that future developers can continue to enhance and maintain the code.
- As an absolute bare minimum, your code must have comments to make it easier to review the code and understand more quickly what is going on in the code.
- More fully, the developer docs include info on
- getting the tools and environment setup to be able to code, build, test, and debug the software
- getting the software (development version)
- installing the software
- understanding how the software is built, tested, and debugged
- contributing to the project with bug reports, patches or pull requests
- "User Docs" is the software manual, targeted at the users of the software (which may include developers or other technical audiences), written in a way as to explain how to use the software:
- getting the software
- installing the software
- using the software in the most common use-cases with examples, illustrations, or videos
- On this last point, a special name for the "User Manual", especially when integrated into the user interface of the software, is "Help". Because systems may be aggregates of several pieces of software, there is often a need for "Help" that addresses how the underlying software is aggregated into that particular system. A perfect example is a wiki (like this one) that includes many 'extensions' to provide specific functionality in addition to what the core software does; and local.
- "API Docs" is a special nuance of Documentation. If your software includes an API, then that API needs to be fully documented almost as a separate piece of software -- for both developers of the API and users of the API.
Contents
Best Practices[edit | edit source]
Having good Developer documentation is a "Best Practice" that has several important positive effects. For adoption (meaning success) of your software, good docs are essential. Actual experience in using the phpDocumentor tool, PyDoc, or other documentation tools is a quality that separates developers from non-developers or senior developers from jr. developers. Writing (good) (formatted) comments into your source code so that docs can be automatically generated on a nightly basis is not optional if you are really interested in your software being successful.
Examples[edit | edit source]
Tools / Generators / Examples[edit | edit source]
phpDocumentor is the best documentation tool for PHP sources with inspiration from JavaDoc.
The PyDoc tool is used to generate documentation on the language itself, and is also leveraged as a framework for developers of help systems and obviously used to document any classes, and methods of source code.
The CiviCRM project, which originally used the Atlassian Confluence Wiki product for documentation, moved over to the (better) Read The Docs system[1] (based on markdown) in a github repository and uses the MkDocs (BSD) static site generator tool to publish to their own domain http://docs.civicrm.org/user/en/4.6/
Meanwhile, the Drupal project has a Documentation Working Group who is using AsciiDoc (GPL) to do the User Guide documentation for Drupal 8
Documenting PHP Code[edit | edit source]
The main resource is the Project website, including tutorials and full Documentation. The system can be installed via the PEAR installer, but should not be setup in an Internet-facing environment. See the PhpDocumentor article for details on our installation and usage.
Documenting other languages[edit | edit source]
Aside from the Python-specific PyDoc, there are ROBODoc (Windows and Fink) and Doxygen tools which should prove to meet all needs. For doxygen, you can
sudo apt-get install doxygen-gui doxygen doxygen-doc
Local Documentation Resources for your Operating System[edit | edit source]
These tips for Linux users on how to reveal man pages, howtos, and other help.
- Create your own internal-use Documentation by creating a symbolic link from /usr/share/docs to /var/www/docs, and fire up your web browser to view your systems documentation.
- info:/dir (type this into the location bar of Konqueror) browse the Info system. You can of course type "info" in your shell, but I find that browsing "info" through Konqueror is a lot nicer.
- man:/command (type this into the location bar of Konqueror) browse the Man system. You can of course type "man command" in your shell, but I find that browsing "manuals" through Konqueror is a lot nicer.
Documentation Documentation[edit | edit source]
OK, so you've adopted all kinds of tools, and procedures for documentation, and you've got multiple people actually writing or contributing to your project's documentation... Great! That means you need some documentation about how you document things :-) Examples:
