rationale updates
@@ -19,18 +19,16 @@ Now it is time to add to it
# Maintenance
-If you want your users be happy you have to keep documentation in sync with you product. It takes time.
-Not every change to the product is a new functionality. But it may still require a documentation update.
+Keeping documentation up-to-date takes time.
+Even non functional changes may require documentation update.
Here are some activities that most likely put your documentation out of sync:
* moving UI elements around
* renaming REST response fields
* removing redundant command line parameters
* renaming public API classes
-This does not mean that we always have to copy-and-paste code snippets, REST responses and retaking screenshots.
-Our code base already contains a wast amount of data. And some extra data can be created by running tests.
-
-Here are some of the things that we can use to make a documentation automatically up-to-date:
+Our code base already contains a wast amount of data.
+Instead of copy-and-paste we leverage artifacts around us.
* examples of how to use API (part of code)
* config files
* test results
@@ -39,5 +37,16 @@ Here are some of the things that we can use to make a documentation automaticall
* CLI
* business logic
-Doing copy-paste between sources takes time and is getting abandoned quickly.
-What we can do instead is refer artifacts that are around code base.
+# Familiar Approach
+
+Markup is everywhere
+* StackOverflow
+* GitHub
+* Jupyter
+* Reddit
+* Discourse
+
+Markup based documentation is widely used as well
+* open source projects (ReactJS, Pandas, Spark)
+* technical books (O'Reilly, Manning)
+* big companies (Google, FaceBook)
\ No newline at end of file
