The goal of this topic is to discuss, document and share any useful information about tools, techniques, tips and consideration for documenting software solutions. Documentation has always been one of the hardest parts of developing a solution, and I hope this guide will get you started down the righteous path. In the end, you should have a project that is ready for public release.
Feel free to ask questions, post comments or any references that will help shed some light on software documentation and user documentation.
Tools
Docusaurus
Docusaurus is a static-site generator . It builds a single-page application with a fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features , but can be used to create any kind of site (personal website, product, blog, marketing landing pages, etc).
Sphnix
Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.
It was originally created for the Python documentation, and it has excellent facilities for the documentation of software projects in a range of languages. Of course, this site is also created from reStructuredText sources using Sphinx! The following features should be highlighted.
Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text
Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
Automatic indices: general index as well as a language-specific module indices
Code handling: automatic highlighting using the Pygments highlighter
Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more
Contributed extensions: dozens of extensions contributed by users; most of them installable from PyPI
Generate A Helpful Changelog From Your Git Commit Messages
[<tag>] (If applied, this commit will...) <subject> (Max 72 char)
|<---- Preferably using up to 50 chars --->|<------------------->|
Example:
[feat] Implement automated commit messages
(Optional) Explain why this change is being made
|<---- Try To Limit Each Line to a Maximum Of 72 Characters ---->|
(Optional) Provide links or keys to any relevant tickets, articles or other resources
Example: Github issue #23
--- COMMIT END ---
Tag can be
feat (new feature)
fix (bug fix)
refactor (refactoring code)
style (formatting, missing semi colons, etc; no code change)
doc (changes to documentation)
test (adding or refactoring tests; no production code change)
version (version bump/new release; no production code change)
jsrXXX (Patches related to the implementation of jsrXXX, where XXX the JSR number)
jdkX (Patches related to supporting jdkX as the host VM, where X the JDK version)
dbg (Changes in debugging code/frameworks; no production code change)
license (Edits regarding licensing; no production code change)
hack (Temporary fix to make things move forward; please avoid it)
WIP (Work In Progress; for intermediate commits to keep patches reasonably sized)
defaults (changes default options)
Note: Multiple tags can be combined, e.g. [fix][jsr292] Fix issue X with methodhandles
--------------------
Remember to:
* Capitalize the subject line
* Use the imperative mood in the subject line
* Do not end the subject line with a period
* Separate subject from body with a blank line
* Use the body to explain what and why vs. how
* Can use multiple lines with "-" or "*" for bullet points in body
The general format for commit messages are:
“<action> [#<issue-number>,] <issue-title> <context>”
Examples:
For temporary fixes
* “Fixed #<issue-number>, <what did you do?> (hack)”
For bug fixes that software related or operating environments, the format should be:
* “Fixed #<issue-number>, <what did you do?>”
For bug fixes that reported by customers:
* “Resolved #<issuse-number>, <the title of the issue> reported by <user>”
For general tasks:
* “Closed #<issuse-number>, <the title of the issue>”
For new feature:
* “Closed #<issuse-number>, <the title of the issue> (new feature)”
For test case:
* “Closed #<issuse-number>, <the title of the issue> (test)”
For documentation:
* “Closed #<issuse-number>, <the title of the issue> (doc)”