From a9b9c70be4f016d293c3a3ef0a4a5ff57db3fd8b Mon Sep 17 00:00:00 2001 From: Rui Miranda Date: Thu, 27 Jun 2019 17:45:48 +0200 Subject: [PATCH 01/15] Add first draft: How to Write Documentation --- README.md | 15 + software_documentation/README.md | 495 +++++++++++++++++++++++++++++++ 2 files changed, 510 insertions(+) create mode 100644 software_documentation/README.md diff --git a/README.md b/README.md index c480904..0e79f1e 100644 --- a/README.md +++ b/README.md @@ -1 +1,16 @@ # knowledge_sharing + + +On this repository you will find several articles worth reading and +spreading. + +Some of them were written to share knowledge with other people, others +were just written as a reminder to myself (i use them as extension for my + memory and reference). + +#Articles + +[How to write good documentation] + +[How to write good documentation] : software_documentation/README.md + diff --git a/software_documentation/README.md b/software_documentation/README.md new file mode 100644 index 0000000..7c9dcf0 --- /dev/null +++ b/software_documentation/README.md @@ -0,0 +1,495 @@ +# How to write good documentation for project + + +## Motivation + +I noticed the Data Engineering tribe at HelloFresh SE was struggling +with the documented the software produced. + +Most of the documentation available on the internet seems to focus either +on project management or a specific sub-topic. + + +This document was initially written in preparation to a "How to Write (Good) + Documentation" learning session at HelloFresh. + +##Tip of the day + +_I spent 3 hours chasing errors to save 5 minutes reading the README.md_ + +## Why Should You Care + + +### Documentation is an extension of your memory + +In a few days, weeks, months you will not longer remember, document +learnings and decisions will pay out in the future + + +### You will need to maintain the code + +You will need to maintain the code in the future, therefore you are making +the documentation to help the future you. + +### You want people to use your code + +You, and your manager, want other people to use your code (or open source project). +There is nothing more frustrating than trying to get a snippet of code and have +no idea why it does not work; If people can't get your code to work, they +will not use it. + +Good documentation is key for people to understand and use your project. + +### Onboarding and User support + +Onboarding is much easier when the tools do work and everything is easy to learn. +Good documentation is key for a positive onboarding experience. + +You should regard the time spent on documentation as an investment, your readers +will have a much better user experience,will spend less time asking you +for support, and you will have more time to work on _important things_. + It is a win-win situation + + +### Less duplication + +One of the reasons why code that duplicates functionality existing within +an organization is because others are not aware of it. Awareness of your +awesome project/code is key to avoid implementation +of similar feature. + +There are lot's of (valid) reasons to have multiple implementations of the same +thing, however ignorance should not be one of them. + + +### You are looking for a new job + +Maybe you are looking for a job, know how to write documentation is skill you +can easily show during a _take home challenge_; therefore you should start +practice it today + + + +## Where should I store my documentation + +Ideally the documentation directed to other software engineers should be checked in +into the version control system. This gives the benefit of having all the documentation: +* all in the same place +* easy to find +* the documentation is also versioned + + +## Different types of Documentation + +There are several kinds of documentation, each one addresses a different problem. +* README.md & other markdown files +* API Documentation: javadoc, scaladoc, python docstrings, Swagger +* data types +* naming +* inline comments in the code +* commit log +* unit tests and tests +* command line parameters + +Apart from the README.md, the remainder of the documentation is mixed with the +code, and this is key to be always up to date. + +### README.md file + + +The README.md is the first contact one does with your code repository, +it should answer questions such as: + +* is here what i am looking for? In other words, what is the purpose of this +repository and does this code do + +* Pre-Requisites (is there any prerequisites that should be ) + +* Building instructions + +* how do i get started (how do i get this running). In other words + +* how do i run unit tests in this thing + +* whom should I contact if I need help + +* contribution guidelines + +* other information + + +Do not assume something is obvious, people really :heart: things that work at +the first attempt; In case of doubt include the information + + +#### Item: _Is this what i am looking for?_ + +You should describe what is the purpose of the project and what does the code +do. The goal is to help the reader decide if the project is relevant or not. + +Good markup titles are: *Motivation*, *Background*, *Overview*, etc. + +#### Item: _Pre-Requisites_ + +In this section you should list all the prerequisites that should be +fulfilled in order to use/run the project. + +You can list here things such as: programing language version, framework version, +data stores, ,other software that needs to be installed, +credentials that are to be obtained, etc. + + +### Item : Building instructions + + +Instructions on how to build the artifact should be provided. Yes it is needed, +just from memory I can tell you the name of 6 tools that build bytecode (JVM). + + + +#### Item: Getting Started + +A step by step guide to get the application to do something. This will allow: + +* to verify the environment is setup properly +* the behaviour of the application to be examined +* the user to modify the toy examples, explore and build more complex things. + +#### Item: How do i run the tests + +If one has to modify the code, she should know how to run the tests to +make sure no unexpected side effect / bug was introduced. + +#### Item: whom should I contact if I need help + +In a corporate environment, hundreds or thousands of people work in tech. +Ideally the team / people maintaining the project should be identifiable. + +#### Item: Contribution Guidelines + +What are the constraints on code contribution? Does the project follow a +specific coding style? naming conventions? design guidelines, pull request +checklist. + +A separate markup file can be created for contribution guidelines. **HelloFresh** +do have a template for contribution guidelines (under software governance) + + +#### Item: Other things you find useful + +There is no such thing as a _one solution fits all_, therefore feel free to +add other information you think useful and do remove items you think don't +fit a specific kind of project. For example, this knowledge sharing project +has no use for unit tests. + +#### Final notes on markup files (and Readme.md) + +Be aware that the README.md is a very good tool for onboarding and quick start, +however because it is not code, it can easily get outdated. Your goal should +mitigate this, by using the most appropriate way of documenting. + +### Other markup files + +Example of other useful markup files are: + +* contribution guidelines +* data exploration / analysis +* how to obtain credentials to use a given service + + +## The Code as Documentation + +The best documentation is not to need documentation, therefore when designing +your abstractions (eg. packages, classes, methods, variables) keep in mind +that the use of meaningful names, that capture the essence of what is happening. + +I know it is not easy, and I have a hard time doing it, but spend some time +choosing the right names for your abstractions; it will also help your structure +your code better. + +Please keep in mind that the **code is written once and read many many many times**. +If you are working on a public API or shared library your quality standard should +be ~~double~~ triple the usual. + +Avoid naming that collide with well known concepts: eg. java interfaces, concepts +from the real world, software pattern names; For example, if a class has factory +in the name, it is expected to be an implementation of the factory software pattern, +however having factory in the name is not a requirement to implement that +software pattern. + +Please do not overuse software patterns, software patterns are supposed to +make the code easy to understand (and by transitivity maintain); they should +not to be used to add unnecessary complexity. There a full list of [Anti Patterns]. + + + +## API Documentation: JavaDoc, ScalaDoc Python Docstrings, Swagger, REST + +When creating API documentation your focus should be on informing the reader +(API client) on what your code does and how the API is used. Details on how your +Code implements the functionality should be omitted. + + +### APIs are final + +When designing you API you should be aware, that usually APIs are final +and only can be changed with great effort. + +Once the API is published someone will start to use it, and +changes will cause code to break. For this reason you should be +very careful when: +* naming API packages +* naming API classes +* naming API methods +* naming API enums + +Please use meaningful naming in the public APIs. In the ideal case, the +naming you use is so good that you would not need any extra documentation. + +### API Documentation will be read/consumed though several channels + +You should be aware + +- The documentation will be read while browse through the code +- The documentation will be read on a fancy-pants _online docs_ build over +your documentation +- The documentation will be shown on the IDE while users are typing the +name of the classes and the methods. + +If you think of the latter two cases, it becomes obvious the reader will +look at the documentation when she want to: +* locate some code which has a given functionality +* learn how to use a given function, method or class + +Therefore the API documentation should focus on what it does and not how it +does it. In other words the **details of the implementation should not be in +the API documentation**; if one want to know how it is implemented, a safari +trip to the source code can always be taken. + + + +### Expose the functionality, hide the details of the implementation + +After the last point it should clear the **API documentation should expose +the functionality and hide the details of the implementation**. A good example +of this is the [Spark Coalesce Documentation], there is even advice on potential +hazardous situations without ever go into the implementation details. + + +If there is an easy way to describe the functionality of a package, class, function +you should prefer that way. + +However, this is not always possible, in those cases you can: +* Use 1 line to give a brief description +* Line break and use more lines if needed +* describe each one of the parameters (include data type on untyped languages) +* don't forget the return type. + + +Checklist: +* get to the point as soon as possible +* if you can do it 1 sentence do it +* summarize the method return value (you can see it as a more succinct version +of the doc) ;this does apply if you can summarize your method in 1 sentence +* do not make references to the details of the implementation +* if you are referring to an instance of the class use the keyword this +(Scala, Java) or self (Python) + + + +##Command Line Documentation + +If your application reads argument from the command line (console), +please use a specialized library (eg. Apache CommonsCli, Python Argparser, etc); + +These use of a library as advantage: +* help you parse the input +* provide description for each argument +* provide help for each argument +* it is usable from the command line +* it is checked in the code repository +* it is always up to date + + +## Tests + +It might not look obvious, but the unit tests are also another way of documenting +your code by providing workable examples. + +According to the [TDD philosophy: tests are executable documentation] +tests are executable documentation. + +Therefore is very important to *write readable tests*, not only to validate a given feature, +but also to be read and understand by a fellow developer. + +### Tests are always up to date + +Unlikely the remainder of the documentation, tests are always up to date; + the CI will fail the build if they are not. + + +### Tests as source of examples + +Tests had been used for a long time as a source of examples on how to use a +give library. I myself quite often look in the unit tests to learn how to +use a given feature of an obscure library. + + + +##On the code + +### Data Types + +Data types provide valuable information about what the variables, attributes +and the expected behaviour of an instance of _something_.. + +Therefore in your Python Docstring include the data type. + +On scala the method return data types and the variable data types are optional. As a +rule of thumb, **if it takes you more than 3 seconds to evaluate the data type of an +expression, please make it explicit**; someone new to the codebase will have a much +harder time make sense of it, and very often the code is so obscure that the IDE also +has a hard time evaluate it to give n hint. + + + +###Meaningful names + +The use of meaningful names for your Classes, Objects, Methods, Class Attributes +and variables will allow the reader to better understand your code. + +* Choosing the right names for your abstractions will help you structure your code/project + + +###Inline comments + +Inline comments are useful to explain why the _[Black Arts]_ of software +engineering are being practiced. + +In other words, the comments are used to explain why a certain "obscure" thing +is being done. Maybe you read it as advice on StackOverflow (and you add the link + as comment), or you are link to a google doc with the stakeholder specification, + or maybe you discovered a certain combination of values throw an exception + and you use an in-line comment do document this. + +Inline comments should be a rare occurrence, but **once in a while they are +the best way to document something**. + + + +## Logging + +Logging plays an important part on the maintenance of an application, +hence should also be considered documentation. + +### Not everything is worth to log + +For example, you are making an HTTP request (with 3 retries), there is not +much value in log every failure; a failure on a HTTP request is a normal thing; +however, a 3 times retry failure is problematic, if the application can’t proceed, +and that is something worth to logging. + +Keep in mind, if every validation error and every exception end in the logs, the logs +lose their (some of) usefulness; Big logs cause a needle in a haystack problem. + +### Administrative Logging + +[Administrative Logs] are very useful to understand the application, in the case of +Data application it’s useful to log the following _adminsitrative_ information: +* Yarn application id +* Paths being loaded +* Output directory + +This information allows you, without checking the code, see if your data processing job +generated any output, if the input directories are empty or locate your job in +The cluster resource manager. + + +###Application Logging + +[A log should be written in English] and shall give context about a failure and allow to identify the root cause; +hence a good log should answer 5 questions: + +- Who (which user, application, cluster node) +- When (timetamp) +- Where (context, class) +- What (command, what was being done) +- Result (Exception) + + + +### Logs to give context to the code + +The logging will also give context your code, and help to understand +what is happening. For example : + +``` + +if (status_code == 401){ + Log.Error("HTTP Status code 401: Unauthorized, please check the application" + + " credentials, could not start the connection with Braze") ; + throw new IlegalStateException("") +} + +``` + +This log will not give valuable information in the log files, but will also +understand the code and what exactly a 401 is. + + + + + +## Commit Log + +The commit log is also a valuable source of documentation. + +Good commit messages enhance features such as log, diff, blame. It helps +understand the changes made, make code review easier and help you structure +your code better. + +Git log should be the source of truth of why changes were made, not Jira. +The ticket system is a tool for the POs, PMs, when trying to understand the +reason of change one should not need to use an additional tool. + +### 7 Commandments of good commit messages + +* Separate subject from body with a blank line +* Limit the subject line to 50 characters +* Capitalize the subject line +* Do not end the subject line with a period +* Use the imperative mood in the subject line +* Wrap the body at 72 characters +* Use the body to explain what and why vs. how + + +Learn more on [How to Write a Good Commit Message] + + + + + + + + + + + + +[How to Write a Good Commit Message]: https://chris.beams.io/posts/git-commit/ + +[TDD philosophy: tests are executable documentation]: https://technologyconversations.com/2014/04/08/tests-as-documentation/ + +[Write Readable Tests]: https://capgemini.github.io/development/unit-tests-as-documentation/ + +[Anti Patterns]: https://en.wikibooks.org/wiki/Introduction_to_Software_Engineering/Architecture/Anti-Patterns + +[Spark Coalesce Documentation]: https://github.com/apache/spark/blob/master/core/src/main/scala/org/apache/spark/rdd/RDD.scala + +[Black Arts]: https://en.wikipedia.org/wiki/Magic_(programming) + +[Administrative Logs]: https://github.com/Haufe-Lexware/Logging---Best-Practices + +[A log should be written in English]: https://www.scalyr.com/blog/the-10-commandments-of-logging/ + +[Logging is an Art]: https://www.codeproject.com/Articles/42354/The-Art-of-Logging \ No newline at end of file From e6edff6d4796250a04e19513d96c8e84706925d2 Mon Sep 17 00:00:00 2001 From: Rui Miranda Date: Thu, 27 Jun 2019 17:49:05 +0200 Subject: [PATCH 02/15] Fix formatting --- README.md | 2 +- software_documentation/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0e79f1e..76be029 100644 --- a/README.md +++ b/README.md @@ -12,5 +12,5 @@ were just written as a reminder to myself (i use them as extension for my [How to write good documentation] -[How to write good documentation] : software_documentation/README.md +[How to write good documentation]: software_documentation/README.md diff --git a/software_documentation/README.md b/software_documentation/README.md index 7c9dcf0..f4f64de 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -13,7 +13,7 @@ on project management or a specific sub-topic. This document was initially written in preparation to a "How to Write (Good) Documentation" learning session at HelloFresh. -##Tip of the day +## Tip of the day _I spent 3 hours chasing errors to save 5 minutes reading the README.md_ From 1e6c1ac24d556984db7e947d34099bdf07e539cd Mon Sep 17 00:00:00 2001 From: Rui Miranda Date: Thu, 27 Jun 2019 17:50:01 +0200 Subject: [PATCH 03/15] Fix Formatting --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 76be029..123ad6e 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Some of them were written to share knowledge with other people, others were just written as a reminder to myself (i use them as extension for my memory and reference). -#Articles +# Articles [How to write good documentation] From 5ec35d24c29d72fedf67c2329f16bda248048c4b Mon Sep 17 00:00:00 2001 From: Rui Miranda Date: Thu, 27 Jun 2019 18:09:05 +0200 Subject: [PATCH 04/15] Add Python Doctest reference to the software_docuemntation --- software_documentation/README.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/software_documentation/README.md b/software_documentation/README.md index f4f64de..985a82a 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -334,6 +334,12 @@ Tests had been used for a long time as a source of examples on how to use a give library. I myself quite often look in the unit tests to learn how to use a given feature of an obscure library. +### Python Doctest + +[Python Doctest] allows to write small unit tests in the Python docstrings. +This is another evidence that unit tests do help the reader of the program +understand what a given method does. + ##On the code @@ -353,7 +359,7 @@ has a hard time evaluate it to give n hint. -###Meaningful names +### Meaningful names The use of meaningful names for your Classes, Objects, Methods, Class Attributes and variables will allow the reader to better understand your code. @@ -361,7 +367,7 @@ and variables will allow the reader to better understand your code. * Choosing the right names for your abstractions will help you structure your code/project -###Inline comments +### Inline comments Inline comments are useful to explain why the _[Black Arts]_ of software engineering are being practiced. @@ -492,4 +498,6 @@ Learn more on [How to Write a Good Commit Message] [A log should be written in English]: https://www.scalyr.com/blog/the-10-commandments-of-logging/ -[Logging is an Art]: https://www.codeproject.com/Articles/42354/The-Art-of-Logging \ No newline at end of file +[Logging is an Art]: https://www.codeproject.com/Articles/42354/The-Art-of-Logging + +[Python Doctest]: https://docs.python.org/2/library/doctest.html \ No newline at end of file From fba0d00e80c94dd440f8446ca0a24bf9f6c2db1d Mon Sep 17 00:00:00 2001 From: Rui Miranda Date: Mon, 1 Jul 2019 13:44:11 +0200 Subject: [PATCH 05/15] Add section on Agile Methodologies --- software_documentation/README.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/software_documentation/README.md b/software_documentation/README.md index 985a82a..49c9c22 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -68,7 +68,29 @@ Maybe you are looking for a job, know how to write documentation is skill you can easily show during a _take home challenge_; therefore you should start practice it today +## Agile Methodologies and Documentation + +> Working software over comprehensive documentation + +The agile manifesto defends a lightweight version of the documentation, not a +zero documentation policy. + +Please defer the creation of documentation to the **latest responsible moment, + possible**. The key word is **responsible**, if you are doing a task that you + forget the steps to replicate it, you need to document it right way; This is, +it is very important to document critical information right away. + +[Agile Documentation Best Practices] key principles for lightweight documentation: + +* Keep documentation just simple enough, but not too simple +* Write the fewest documents with least overlap +* Put the information in the most appropriate place + + +Documentation as part of the software development process should also be +included in the estimations and planing. + ## Where should I store my documentation @@ -77,6 +99,7 @@ into the version control system. This gives the benefit of having all the docume * all in the same place * easy to find * the documentation is also versioned +* principle of single source of information ## Different types of Documentation @@ -444,8 +467,6 @@ understand the code and what exactly a 401 is. - - ## Commit Log The commit log is also a valuable source of documentation. @@ -500,4 +521,6 @@ Learn more on [How to Write a Good Commit Message] [Logging is an Art]: https://www.codeproject.com/Articles/42354/The-Art-of-Logging -[Python Doctest]: https://docs.python.org/2/library/doctest.html \ No newline at end of file +[Python Doctest]: https://docs.python.org/2/library/doctest.html + +[Agile Documentation Best Practices]: http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm \ No newline at end of file From 51e040c1df3c819c0488c730903b55f226f4a29e Mon Sep 17 00:00:00 2001 From: Rui Miranda Date: Mon, 1 Jul 2019 15:46:38 +0200 Subject: [PATCH 06/15] Add ticket system and work unit (commit log) Sections about the role of the ticket system (eg. Jira) and that commits should be seen as work unit should were added. --- software_documentation/README.md | 55 +++++++++++++++++++++++++++----- 1 file changed, 47 insertions(+), 8 deletions(-) diff --git a/software_documentation/README.md b/software_documentation/README.md index 49c9c22..bf2e4e1 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -475,9 +475,53 @@ Good commit messages enhance features such as log, diff, blame. It helps understand the changes made, make code review easier and help you structure your code better. -Git log should be the source of truth of why changes were made, not Jira. -The ticket system is a tool for the POs, PMs, when trying to understand the -reason of change one should not need to use an additional tool. + +##The Ticket System (Jira) is good to track customer requests and project +management + + +Git log should be the source of information of why changes were made, not Jira. +> User Story: On table X provide attribute Y + +does not look like much of a reason why implementation A is favored over B, does it? + +When you perform a _diff_ or a _blame_ over the code you want to understand why +that specific change was done, therefore is critical the information is stored +in the version control. + +Of course, you should put a reference to the ticket system if relevant and gives +context, however the commit log should be enough. + +### The commit as a work unit + +Things might get easier if you see each commit as a work unit. +Therefore each commit should only have related things. + +As guideline can you describe the all the changes happening in a single +commit commit message? +* No => break into describable things +* Yes => Would you be comfortable do a code review on a commit that size? + * no => break further + * yes => you are good to go (: + + +For example: +> Add feature X and Fix code formatting in the same commit + +Bad: The formatting cleanup will cause unrelated changes with feature X to the +commit, which will make, for example, the code-review harder. + +> Changes based on code review + +Bad: this message does not capture the reason why the change were does. You +probably followed several suggestions on your reviews hence, you could +have done one for each suggestion. + + +You probably already know, but it is possible to go through each commit on +code review; hence good commits will help you make structure better +your pull requests and will also help your reviewer. + ### 7 Commandments of good commit messages @@ -498,11 +542,6 @@ Learn more on [How to Write a Good Commit Message] - - - - - [How to Write a Good Commit Message]: https://chris.beams.io/posts/git-commit/ [TDD philosophy: tests are executable documentation]: https://technologyconversations.com/2014/04/08/tests-as-documentation/ From f8e5f9ea064d924da0a96069036d95a1b623ed54 Mon Sep 17 00:00:00 2001 From: Rui Miranda Date: Mon, 1 Jul 2019 17:44:44 +0200 Subject: [PATCH 07/15] Add the properties of the good documentation --- software_documentation/README.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/software_documentation/README.md b/software_documentation/README.md index bf2e4e1..784a9bf 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -91,6 +91,18 @@ it is very important to document critical information right away. Documentation as part of the software development process should also be included in the estimations and planing. + +[Properties of good documentation] + +* Current => __incorrect documentation is worse than missing documentation__ +* Nearby => Ideally in the same repository as the code +* Unique => principle of the single source of information. If documentation is +duplicate extra effort to maintain it needs to be done +* Discoverable => Documentation should be in the place where the users (naturally) +look for it, there is no need to duplicate, you can link the documentation. + + + ## Where should I store my documentation @@ -539,9 +551,6 @@ Learn more on [How to Write a Good Commit Message] - - - [How to Write a Good Commit Message]: https://chris.beams.io/posts/git-commit/ [TDD philosophy: tests are executable documentation]: https://technologyconversations.com/2014/04/08/tests-as-documentation/ @@ -562,4 +571,6 @@ Learn more on [How to Write a Good Commit Message] [Python Doctest]: https://docs.python.org/2/library/doctest.html -[Agile Documentation Best Practices]: http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm \ No newline at end of file +[Agile Documentation Best Practices]: http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm + +[Properties of good documentation]: https://www.writethedocs.org/guide/writing/docs-principles/ From 44aaa6f1aeb6e9783efa8cc4a95f210d38e0db8f Mon Sep 17 00:00:00 2001 From: Rui Miranda Date: Mon, 1 Jul 2019 18:01:49 +0200 Subject: [PATCH 08/15] Give examples of the Single Source of Information --- software_documentation/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/software_documentation/README.md b/software_documentation/README.md index 784a9bf..b5f5b3f 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -302,6 +302,12 @@ the API documentation**; if one want to know how it is implemented, a safari trip to the source code can always be taken. +:star2: dedicated pages such as javadoc, scaladoc, pythondoc, readthedocs +are a good example on how the _single source of information_ (the code) +is converted into a different way of delivering the documentation. Because this +_fancy pants_ html pages are generated from the source code of the application, +they will always be in sync with the source code. + ### Expose the functionality, hide the details of the implementation @@ -345,6 +351,8 @@ These use of a library as advantage: * it is checked in the code repository * it is always up to date +:star2: Another great example of the single source of information. The help +given by the command line will always be up to date with the source code. ## Tests From 8001cafca79fddf76b025506b9c9ce3a8a5f8090 Mon Sep 17 00:00:00 2001 From: Rui Miranda Date: Mon, 1 Jul 2019 18:51:39 +0200 Subject: [PATCH 09/15] Review some style and grammar of the document --- software_documentation/README.md | 95 +++++++++++++++++--------------- 1 file changed, 50 insertions(+), 45 deletions(-) diff --git a/software_documentation/README.md b/software_documentation/README.md index b5f5b3f..94261e1 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -22,32 +22,32 @@ _I spent 3 hours chasing errors to save 5 minutes reading the README.md_ ### Documentation is an extension of your memory -In a few days, weeks, months you will not longer remember, document +In a few days, weeks, months you will not longer remember, document learnings and decisions will pay out in the future ### You will need to maintain the code -You will need to maintain the code in the future, therefore you are making +You will need to maintain the code in the future; therefore you are making the documentation to help the future you. ### You want people to use your code -You, and your manager, want other people to use your code (or open source project). -There is nothing more frustrating than trying to get a snippet of code and have -no idea why it does not work; If people can't get your code to work, they -will not use it. +You, and your manager, want other people to use your code (or open source + project). There is nothing more frustrating than trying to get a snippet + of code and have no idea why it does not work; If people can't get your + code to work, they will not use it. Good documentation is key for people to understand and use your project. ### Onboarding and User support Onboarding is much easier when the tools do work and everything is easy to learn. -Good documentation is key for a positive onboarding experience. +Good documentation is key for a positive onboarding experience. -You should regard the time spent on documentation as an investment, your readers -will have a much better user experience,will spend less time asking you -for support, and you will have more time to work on _important things_. +You should regard the time spent on documentation as an investment, your + readers will have a much better user experience, will spend less time asking + you for support, and you will have more time to work on _important things_. It is a win-win situation @@ -58,15 +58,15 @@ an organization is because others are not aware of it. Awareness of your awesome project/code is key to avoid implementation of similar feature. -There are lot's of (valid) reasons to have multiple implementations of the same -thing, however ignorance should not be one of them. +There are lot of (valid) reasons to have multiple implementations of the same +thing; however ignorance should not be one of them. ### You are looking for a new job Maybe you are looking for a job, know how to write documentation is skill you can easily show during a _take home challenge_; therefore you should start -practice it today +practice it today. ## Agile Methodologies and Documentation @@ -81,7 +81,8 @@ Please defer the creation of documentation to the **latest responsible moment, it is very important to document critical information right away. -[Agile Documentation Best Practices] key principles for lightweight documentation: +According to the [Agile Documentation Best Practices], the key principles for + lightweight documentation: * Keep documentation just simple enough, but not too simple * Write the fewest documents with least overlap @@ -89,7 +90,7 @@ it is very important to document critical information right away. Documentation as part of the software development process should also be -included in the estimations and planing. +included in the estimations and planning. [Properties of good documentation] @@ -104,14 +105,14 @@ look for it, there is no need to duplicate, you can link the documentation. -## Where should I store my documentation +## Use the version control for your documentation Ideally the documentation directed to other software engineers should be checked in into the version control system. This gives the benefit of having all the documentation: -* all in the same place -* easy to find -* the documentation is also versioned -* principle of single source of information +* All in the same place +* Easy to find +* The documentation is also versioned +* Principle of single source of information ## Different types of Documentation @@ -119,12 +120,11 @@ into the version control system. This gives the benefit of having all the docume There are several kinds of documentation, each one addresses a different problem. * README.md & other markdown files * API Documentation: javadoc, scaladoc, python docstrings, Swagger -* data types -* naming -* inline comments in the code -* commit log -* unit tests and tests -* command line parameters +* Naming +* Inline comments in the code +* Commit log +* Unit tests and tests +* Command line parameters Apart from the README.md, the remainder of the documentation is mixed with the code, and this is key to be always up to date. @@ -135,31 +135,34 @@ code, and this is key to be always up to date. The README.md is the first contact one does with your code repository, it should answer questions such as: -* is here what i am looking for? In other words, what is the purpose of this +* Is this what I am looking for? In other words, what is the purpose of this repository and does this code do -* Pre-Requisites (is there any prerequisites that should be ) +* Pre-Requisites (are there any prerequisites I should comply with to +run this code? Do I need to install any software?) * Building instructions -* how do i get started (how do i get this running). In other words +* How do I get started (how do i get this running). -* how do i run unit tests in this thing +* How do I run the unit tests in this thing -* whom should I contact if I need help +* Whom should I contact if I need help -* contribution guidelines +* Contribution guidelines -* other information +* Other information Do not assume something is obvious, people really :heart: things that work at -the first attempt; In case of doubt include the information +the first attempt; In case of doubt include the information. You don't know +if a developer from other team (eg. backend) is assigned to add a field to + _your_ data pipeline. #### Item: _Is this what i am looking for?_ -You should describe what is the purpose of the project and what does the code +You should describe what is the purpose of the project, and what does the code do. The goal is to help the reader decide if the project is relevant or not. Good markup titles are: *Motivation*, *Background*, *Overview*, etc. @@ -169,9 +172,9 @@ Good markup titles are: *Motivation*, *Background*, *Overview*, etc. In this section you should list all the prerequisites that should be fulfilled in order to use/run the project. -You can list here things such as: programing language version, framework version, -data stores, ,other software that needs to be installed, -credentials that are to be obtained, etc. +You can list here things such as: programming language version, framework + version, data stores, other software that needs to be installed, + credentials that are to be obtained, etc. ### Item : Building instructions @@ -184,16 +187,16 @@ just from memory I can tell you the name of 6 tools that build bytecode (JVM). #### Item: Getting Started -A step by step guide to get the application to do something. This will allow: +A step-by-step guide to get the application to do something. This will allow: -* to verify the environment is setup properly -* the behaviour of the application to be examined -* the user to modify the toy examples, explore and build more complex things. +* To verify the environment is setup properly +* The behaviour of the application to be examined +* The user to modify the toy examples, explore and build more complex things. #### Item: How do i run the tests If one has to modify the code, she should know how to run the tests to -make sure no unexpected side effect / bug was introduced. +make sure no unexpected side-effect / bug was introduced. #### Item: whom should I contact if I need help @@ -223,6 +226,8 @@ Be aware that the README.md is a very good tool for onboarding and quick start, however because it is not code, it can easily get outdated. Your goal should mitigate this, by using the most appropriate way of documenting. +:warning: beware wrong instructions are worst than no instructions at all + ### Other markup files Example of other useful markup files are: @@ -456,8 +461,8 @@ The cluster resource manager. ###Application Logging -[A log should be written in English] and shall give context about a failure and allow to identify the root cause; -hence a good log should answer 5 questions: +[A log should be written in English] and shall give context about a failure +and allow to identify the root cause; hence a good log should answer 5 questions: - Who (which user, application, cluster node) - When (timetamp) From 6a467e3a9acfa333a6c7c53e83e913d5fe603cae Mon Sep 17 00:00:00 2001 From: rui Date: Tue, 2 Jul 2019 00:34:35 +0200 Subject: [PATCH 10/15] Review more style and grammar of the document --- software_documentation/README.md | 106 +++++++++++++++---------------- 1 file changed, 51 insertions(+), 55 deletions(-) diff --git a/software_documentation/README.md b/software_documentation/README.md index 94261e1..7f42e00 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -251,15 +251,14 @@ Please keep in mind that the **code is written once and read many many many time If you are working on a public API or shared library your quality standard should be ~~double~~ triple the usual. -Avoid naming that collide with well known concepts: eg. java interfaces, concepts +Avoid naming that collide with well-known concepts: eg. java interfaces, concepts from the real world, software pattern names; For example, if a class has factory -in the name, it is expected to be an implementation of the factory software pattern, -however having factory in the name is not a requirement to implement that -software pattern. +in the name, it is expected to be an implementation of the factory software pattern; +however the naming is not a requirement to implement any software patern. Please do not overuse software patterns, software patterns are supposed to make the code easy to understand (and by transitivity maintain); they should -not to be used to add unnecessary complexity. There a full list of [Anti Patterns]. +not be used to add unnecessary complexity. There is a full list of [Anti Patterns]. @@ -276,12 +275,12 @@ When designing you API you should be aware, that usually APIs are final and only can be changed with great effort. Once the API is published someone will start to use it, and -changes will cause code to break. For this reason you should be +changes will cause code to break; hence you should be very careful when: -* naming API packages -* naming API classes -* naming API methods -* naming API enums +* Naming API packages +* Naming API classes +* Naming API methods +* Naming API enums Please use meaningful naming in the public APIs. In the ideal case, the naming you use is so good that you would not need any extra documentation. @@ -291,15 +290,14 @@ naming you use is so good that you would not need any extra documentation. You should be aware - The documentation will be read while browse through the code -- The documentation will be read on a fancy-pants _online docs_ build over -your documentation +- The documentation will be read on a web fancy-pants _online docs_ build from the source code - The documentation will be shown on the IDE while users are typing the name of the classes and the methods. If you think of the latter two cases, it becomes obvious the reader will look at the documentation when she want to: -* locate some code which has a given functionality -* learn how to use a given function, method or class +* Locate some code which has a given functionality +* Learn how to use a given function, method or class Therefore the API documentation should focus on what it does and not how it does it. In other words the **details of the implementation should not be in @@ -309,7 +307,7 @@ trip to the source code can always be taken. :star2: dedicated pages such as javadoc, scaladoc, pythondoc, readthedocs are a good example on how the _single source of information_ (the code) -is converted into a different way of delivering the documentation. Because this +is converted into a different way of delivering the documentation. This _fancy pants_ html pages are generated from the source code of the application, they will always be in sync with the source code. @@ -318,8 +316,8 @@ they will always be in sync with the source code. After the last point it should clear the **API documentation should expose the functionality and hide the details of the implementation**. A good example -of this is the [Spark Coalesce Documentation], there is even advice on potential -hazardous situations without ever go into the implementation details. +of this is the [Spark Coalesce Documentation], it gives advice on potential +hazardous situations without ever going into the implementation details. If there is an easy way to describe the functionality of a package, class, function @@ -328,17 +326,17 @@ you should prefer that way. However, this is not always possible, in those cases you can: * Use 1 line to give a brief description * Line break and use more lines if needed -* describe each one of the parameters (include data type on untyped languages) -* don't forget the return type. +* Describe each one of the parameters (include data type on untyped languages) +* Don't forget the return type. Checklist: -* get to the point as soon as possible -* if you can do it 1 sentence do it -* summarize the method return value (you can see it as a more succinct version +* Get to the point as soon as possible +* If you can do it 1 sentence do it +* Summarize the method return value (you can see it as a more succinct version of the doc) ;this does apply if you can summarize your method in 1 sentence -* do not make references to the details of the implementation -* if you are referring to an instance of the class use the keyword this +* Do not make references to the details of the implementation +* If you are referring to an instance of the class use the keyword this (Scala, Java) or self (Python) @@ -348,13 +346,13 @@ of the doc) ;this does apply if you can summarize your method in 1 sentence If your application reads argument from the command line (console), please use a specialized library (eg. Apache CommonsCli, Python Argparser, etc); -These use of a library as advantage: -* help you parse the input -* provide description for each argument -* provide help for each argument -* it is usable from the command line -* it is checked in the code repository -* it is always up to date +It brings several advantage: +* Help you parse the input +* Provide description for each argument +* Provide help for each argument +* It is usable from the command line +* It is checked in the code repository +* It documentation is always up-to-date :star2: Another great example of the single source of information. The help given by the command line will always be up to date with the source code. @@ -364,22 +362,21 @@ given by the command line will always be up to date with the source code. It might not look obvious, but the unit tests are also another way of documenting your code by providing workable examples. -According to the [TDD philosophy: tests are executable documentation] -tests are executable documentation. +Additionally, according to the [TDD philosophy: tests are executable documentation]. -Therefore is very important to *write readable tests*, not only to validate a given feature, +Therefore, it is very important to *write readable tests*, not only to validate a given feature, but also to be read and understand by a fellow developer. -### Tests are always up to date +### Tests are always up-to-date -Unlikely the remainder of the documentation, tests are always up to date; +Unlikely the remainder of the documentation, tests are always up-to-date; the CI will fail the build if they are not. ### Tests as source of examples Tests had been used for a long time as a source of examples on how to use a -give library. I myself quite often look in the unit tests to learn how to +give library. I myself, quite often look in the unit tests to learn how to use a given feature of an obscure library. ### Python Doctest @@ -401,8 +398,8 @@ Therefore in your Python Docstring include the data type. On scala the method return data types and the variable data types are optional. As a rule of thumb, **if it takes you more than 3 seconds to evaluate the data type of an -expression, please make it explicit**; someone new to the codebase will have a much -harder time make sense of it, and very often the code is so obscure that the IDE also +expression, please make it explicit**. Someone new to the codebase will have a much +harder time make sense of it;administrative and very often the code is so obscure that the IDE also has a hard time evaluate it to give n hint. @@ -449,23 +446,23 @@ lose their (some of) usefulness; Big logs cause a needle in a haystack problem. ### Administrative Logging [Administrative Logs] are very useful to understand the application, in the case of -Data application it’s useful to log the following _adminsitrative_ information: +Data application it’s useful to log the following _administrative_ information: * Yarn application id * Paths being loaded * Output directory This information allows you, without checking the code, see if your data processing job generated any output, if the input directories are empty or locate your job in -The cluster resource manager. +the cluster resource manager. ###Application Logging -[A log should be written in English] and shall give context about a failure +[A log should be written in English] and should give context about a failure and allow to identify the root cause; hence a good log should answer 5 questions: - Who (which user, application, cluster node) -- When (timetamp) +- When (timestamp) - Where (context, class) - What (command, what was being done) - Result (Exception) @@ -474,7 +471,7 @@ and allow to identify the root cause; hence a good log should answer 5 questions ### Logs to give context to the code -The logging will also give context your code, and help to understand +The logging will also give context your code, and help you understand what is happening. For example : ``` @@ -487,8 +484,7 @@ if (status_code == 401){ ``` -This log will not give valuable information in the log files, but will also -understand the code and what exactly a 401 is. +This log will not only give valuable information in the log files, but will also point to the problem at hand. @@ -510,19 +506,19 @@ Git log should be the source of information of why changes were made, not Jira. does not look like much of a reason why implementation A is favored over B, does it? -When you perform a _diff_ or a _blame_ over the code you want to understand why -that specific change was done, therefore is critical the information is stored +When you perform a _diff_ or a _blame_ over the code, you want to understand why +that specific change was done; therefore is critical the information is stored in the version control. -Of course, you should put a reference to the ticket system if relevant and gives +Of course, you should put a reference to the ticket system if it is relevant and gives context, however the commit log should be enough. ### The commit as a work unit -Things might get easier if you see each commit as a work unit. -Therefore each commit should only have related things. +Things might get easier if you see each commit as a work unit; +therefore each commit should only have related things. -As guideline can you describe the all the changes happening in a single +As guideline can you describe all the changes happening in a single commit commit message? * No => break into describable things * Yes => Would you be comfortable do a code review on a commit that size? @@ -538,9 +534,9 @@ commit, which will make, for example, the code-review harder. > Changes based on code review -Bad: this message does not capture the reason why the change were does. You -probably followed several suggestions on your reviews hence, you could -have done one for each suggestion. +Bad: this message does not capture the reason why the change were done. You +probably followed several suggestions on your reviews; hence you probably could +have isolated each change in a separate commit. You probably already know, but it is possible to go through each commit on From 5295c3b9ddfb847dfbf158f302ebc28cbb53e640 Mon Sep 17 00:00:00 2001 From: Rui Miranda Date: Tue, 2 Jul 2019 12:01:56 +0200 Subject: [PATCH 11/15] Captitalize the titles --- software_documentation/README.md | 68 ++++++++++++++++---------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/software_documentation/README.md b/software_documentation/README.md index 7f42e00..bc38069 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -1,4 +1,4 @@ -# How to write good documentation for project +# How To Write Good Documentation For Project ## Motivation @@ -13,25 +13,25 @@ on project management or a specific sub-topic. This document was initially written in preparation to a "How to Write (Good) Documentation" learning session at HelloFresh. -## Tip of the day +## Tip Of The Day _I spent 3 hours chasing errors to save 5 minutes reading the README.md_ ## Why Should You Care -### Documentation is an extension of your memory +### Documentation Is An Extension Of Your Memory In a few days, weeks, months you will not longer remember, document learnings and decisions will pay out in the future -### You will need to maintain the code +### You Will Need To Maintain The Code You will need to maintain the code in the future; therefore you are making the documentation to help the future you. -### You want people to use your code +### You Want People To Use Your Code You, and your manager, want other people to use your code (or open source project). There is nothing more frustrating than trying to get a snippet @@ -40,7 +40,7 @@ You, and your manager, want other people to use your code (or open source Good documentation is key for people to understand and use your project. -### Onboarding and User support +### Onboarding And User Support Onboarding is much easier when the tools do work and everything is easy to learn. Good documentation is key for a positive onboarding experience. @@ -51,7 +51,7 @@ You should regard the time spent on documentation as an investment, your It is a win-win situation -### Less duplication +### Less Duplication One of the reasons why code that duplicates functionality existing within an organization is because others are not aware of it. Awareness of your @@ -62,13 +62,13 @@ There are lot of (valid) reasons to have multiple implementations of the same thing; however ignorance should not be one of them. -### You are looking for a new job +### You Are Looking For A New Job Maybe you are looking for a job, know how to write documentation is skill you can easily show during a _take home challenge_; therefore you should start practice it today. -## Agile Methodologies and Documentation +## Agile Methodologies And Documentation > Working software over comprehensive documentation @@ -105,7 +105,7 @@ look for it, there is no need to duplicate, you can link the documentation. -## Use the version control for your documentation +## Use The Version Control For Your Documentation Ideally the documentation directed to other software engineers should be checked in into the version control system. This gives the benefit of having all the documentation: @@ -115,7 +115,7 @@ into the version control system. This gives the benefit of having all the docume * Principle of single source of information -## Different types of Documentation +## Different Types Of Documentation There are several kinds of documentation, each one addresses a different problem. * README.md & other markdown files @@ -129,7 +129,7 @@ There are several kinds of documentation, each one addresses a different problem Apart from the README.md, the remainder of the documentation is mixed with the code, and this is key to be always up to date. -### README.md file +### README.md File The README.md is the first contact one does with your code repository, @@ -160,7 +160,7 @@ if a developer from other team (eg. backend) is assigned to add a field to _your_ data pipeline. -#### Item: _Is this what i am looking for?_ +#### Item: _Is This What I Am Looking For?_ You should describe what is the purpose of the project, and what does the code do. The goal is to help the reader decide if the project is relevant or not. @@ -177,7 +177,7 @@ You can list here things such as: programming language version, framework credentials that are to be obtained, etc. -### Item : Building instructions +### Item : Building Instructions Instructions on how to build the artifact should be provided. Yes it is needed, @@ -193,12 +193,12 @@ A step-by-step guide to get the application to do something. This will allow: * The behaviour of the application to be examined * The user to modify the toy examples, explore and build more complex things. -#### Item: How do i run the tests +#### Item: How Do I Run The Tests If one has to modify the code, she should know how to run the tests to make sure no unexpected side-effect / bug was introduced. -#### Item: whom should I contact if I need help +#### Item: Whom Should I Contact If I Need Help In a corporate environment, hundreds or thousands of people work in tech. Ideally the team / people maintaining the project should be identifiable. @@ -213,14 +213,14 @@ A separate markup file can be created for contribution guidelines. **HelloFresh do have a template for contribution guidelines (under software governance) -#### Item: Other things you find useful +#### Item: Other Things You Find Useful There is no such thing as a _one solution fits all_, therefore feel free to add other information you think useful and do remove items you think don't fit a specific kind of project. For example, this knowledge sharing project has no use for unit tests. -#### Final notes on markup files (and Readme.md) +#### Final Notes On Markup Files (And Readme.md) Be aware that the README.md is a very good tool for onboarding and quick start, however because it is not code, it can easily get outdated. Your goal should @@ -228,7 +228,7 @@ mitigate this, by using the most appropriate way of documenting. :warning: beware wrong instructions are worst than no instructions at all -### Other markup files +### Other Markup Files Example of other useful markup files are: @@ -237,7 +237,7 @@ Example of other useful markup files are: * how to obtain credentials to use a given service -## The Code as Documentation +## The Code As Documentation The best documentation is not to need documentation, therefore when designing your abstractions (eg. packages, classes, methods, variables) keep in mind @@ -269,7 +269,7 @@ When creating API documentation your focus should be on informing the reader Code implements the functionality should be omitted. -### APIs are final +### APIs Are Final When designing you API you should be aware, that usually APIs are final and only can be changed with great effort. @@ -285,7 +285,7 @@ very careful when: Please use meaningful naming in the public APIs. In the ideal case, the naming you use is so good that you would not need any extra documentation. -### API Documentation will be read/consumed though several channels +### API Documentation Will Be Read/Consumed Though Several Channels You should be aware @@ -312,7 +312,7 @@ _fancy pants_ html pages are generated from the source code of the application, they will always be in sync with the source code. -### Expose the functionality, hide the details of the implementation +### Expose The Functionality, Hide The Details Of The Implementation After the last point it should clear the **API documentation should expose the functionality and hide the details of the implementation**. A good example @@ -367,13 +367,13 @@ Additionally, according to the [TDD philosophy: tests are executable documentati Therefore, it is very important to *write readable tests*, not only to validate a given feature, but also to be read and understand by a fellow developer. -### Tests are always up-to-date +### Tests Are Always Up-To-Date Unlikely the remainder of the documentation, tests are always up-to-date; the CI will fail the build if they are not. -### Tests as source of examples +### Tests As Source Of Examples Tests had been used for a long time as a source of examples on how to use a give library. I myself, quite often look in the unit tests to learn how to @@ -387,7 +387,7 @@ understand what a given method does. -##On the code +##On The Code ### Data Types @@ -404,7 +404,7 @@ has a hard time evaluate it to give n hint. -### Meaningful names +### Meaningful Names The use of meaningful names for your Classes, Objects, Methods, Class Attributes and variables will allow the reader to better understand your code. @@ -412,7 +412,7 @@ and variables will allow the reader to better understand your code. * Choosing the right names for your abstractions will help you structure your code/project -### Inline comments +### Inline Comments Inline comments are useful to explain why the _[Black Arts]_ of software engineering are being practiced. @@ -433,7 +433,7 @@ the best way to document something**. Logging plays an important part on the maintenance of an application, hence should also be considered documentation. -### Not everything is worth to log +### Not Everything Is Worth To Log For example, you are making an HTTP request (with 3 retries), there is not much value in log every failure; a failure on a HTTP request is a normal thing; @@ -469,7 +469,7 @@ and allow to identify the root cause; hence a good log should answer 5 questions -### Logs to give context to the code +### Logs To Give Context To The Code The logging will also give context your code, and help you understand what is happening. For example : @@ -497,8 +497,8 @@ understand the changes made, make code review easier and help you structure your code better. -##The Ticket System (Jira) is good to track customer requests and project -management +##The Ticket System (Jira) Is Good To Track Customer Requests And Project +Management Git log should be the source of information of why changes were made, not Jira. @@ -513,7 +513,7 @@ in the version control. Of course, you should put a reference to the ticket system if it is relevant and gives context, however the commit log should be enough. -### The commit as a work unit +### The Commit As A Work Unit Things might get easier if you see each commit as a work unit; therefore each commit should only have related things. @@ -544,7 +544,7 @@ code review; hence good commits will help you make structure better your pull requests and will also help your reviewer. -### 7 Commandments of good commit messages +### 7 Commandments Of Good Commit Messages * Separate subject from body with a blank line * Limit the subject line to 50 characters From 004e4218759d364958613e68281cc433f1766f01 Mon Sep 17 00:00:00 2001 From: Rui Miranda Date: Tue, 2 Jul 2019 13:31:25 +0200 Subject: [PATCH 12/15] Remove tip of the day --- software_documentation/README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/software_documentation/README.md b/software_documentation/README.md index bc38069..ff03001 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -13,9 +13,6 @@ on project management or a specific sub-topic. This document was initially written in preparation to a "How to Write (Good) Documentation" learning session at HelloFresh. -## Tip Of The Day - -_I spent 3 hours chasing errors to save 5 minutes reading the README.md_ ## Why Should You Care From ae954be8dee9ca238c5e0e9e147aadc8600e0399 Mon Sep 17 00:00:00 2001 From: Rui Miranda Date: Tue, 2 Jul 2019 15:23:00 +0200 Subject: [PATCH 13/15] Fix formatting --- software_documentation/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/software_documentation/README.md b/software_documentation/README.md index ff03001..cf161e2 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -4,7 +4,7 @@ ## Motivation I noticed the Data Engineering tribe at HelloFresh SE was struggling -with the documented the software produced. + documenting the produced software. Most of the documentation available on the internet seems to focus either on project management or a specific sub-topic. @@ -333,12 +333,12 @@ Checklist: * Summarize the method return value (you can see it as a more succinct version of the doc) ;this does apply if you can summarize your method in 1 sentence * Do not make references to the details of the implementation -* If you are referring to an instance of the class use the keyword this -(Scala, Java) or self (Python) +* If you are referring to an instance of the class use the keyword _this_ +(Scala, Java) or _self_ (Python) -##Command Line Documentation +## Command Line Documentation If your application reads argument from the command line (console), please use a specialized library (eg. Apache CommonsCli, Python Argparser, etc); @@ -384,7 +384,7 @@ understand what a given method does. -##On The Code +## On The Code ### Data Types @@ -453,7 +453,7 @@ generated any output, if the input directories are empty or locate your job in the cluster resource manager. -###Application Logging +### Application Logging [A log should be written in English] and should give context about a failure and allow to identify the root cause; hence a good log should answer 5 questions: @@ -494,7 +494,7 @@ understand the changes made, make code review easier and help you structure your code better. -##The Ticket System (Jira) Is Good To Track Customer Requests And Project +## The Ticket System (Jira) Is Good To Track Customer Requests And Project Management From 2916b85b9bb6cf654d0cca4f789fde1bf33e6bf7 Mon Sep 17 00:00:00 2001 From: rui Date: Wed, 3 Jul 2019 23:47:06 +0200 Subject: [PATCH 14/15] Add links to README.md examples --- software_documentation/README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/software_documentation/README.md b/software_documentation/README.md index cf161e2..30cea08 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -225,6 +225,11 @@ mitigate this, by using the most appropriate way of documenting. :warning: beware wrong instructions are worst than no instructions at all +#### Readme.md Examples: +Good Readme.md files are for example: [aws encryption sdk], [aws sdk java], + [Apache Spark] or [Closure Compiler (Google)]; There is plenty of good + examples on github. + ### Other Markup Files Example of other useful markup files are: @@ -580,3 +585,15 @@ Learn more on [How to Write a Good Commit Message] [Agile Documentation Best Practices]: http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm [Properties of good documentation]: https://www.writethedocs.org/guide/writing/docs-principles/ + + + + +[aws encryption sdk]: https://github.com/aws/aws-encryption-sdk-python +[aws sdk java]: https://github.com/aws/aws-sdk-java +[Apache Spark]: https://github.com/apache/spark +[Closure Compiler (Google)]: https://github.com/google/closure-compiler + +[Linux Kernel]: https://github.com/torvalds/linux/commits/master + + From 12f92094441423516e2597dabb4d3dceb2a2a091 Mon Sep 17 00:00:00 2001 From: iamwrong Date: Mon, 8 Jul 2019 13:36:15 +0200 Subject: [PATCH 15/15] Change the title (add pronoun) --- software_documentation/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/software_documentation/README.md b/software_documentation/README.md index 30cea08..fc46e36 100644 --- a/software_documentation/README.md +++ b/software_documentation/README.md @@ -1,4 +1,4 @@ -# How To Write Good Documentation For Project +# How To Write Good Documentation For Your Project ## Motivation