Documentation 3.5 Improvement #493
Replies: 5 comments 2 replies
-
|
Thank you @kiwisincebirth. I agree with almost all of this. I would like to keep the Release Notes as a separate document because I want to ensure it is extremely simple for users to access via links I intend to place in many places. I prefer users not need to look through another document to find the Release Notes. I am swamped right now (testing v3.5 and some personal stuff). You are welcome to pursue these doucmentation improvements, otherwise I will try to take care of it prior to finalizing v3.5. Thanks, Wayne |
Beta Was this translation helpful? Give feedback.
-
|
See PR #494 After I did most of the work, i went to update /source/doc/readme.md (contributions list) then discovered
So basically my idea of an Introduction PDF document is closely aligned to content behind the projects readme. Noting : I did do some reorganisation of Introduction.PDF to provide slightly better flow. So where did I leave it.
However: There is an opportunity to combine / reduce to a single Readme/Introduction document, removing alot of duplication. The primary differences between the 2 documents are:
|
Beta Was this translation helpful? Give feedback.
-
|
The high-level ReadMe document has always been an extract of portions of the User Guide. I started to resync ReadMe with the new Introduction document, but soon realized that the content of the Introduction document was actually very similar to the ReadMe. Now that we have the Introduction document, does it make sense to use it instead of ReadMe? |
Beta Was this translation helpful? Give feedback.
-
So you came to same realisation.
I don't think we do. That was my point above, but wanted your buy-in since it affects to project level readme. In summary think want is needed is to Delete /source/doc/ReadMe.MD, and Update the build scripts to use Introduction.MD in its place. |
Beta Was this translation helpful? Give feedback.
-
|
The only other tweak's I would be to
Which is addressed in #495 |
Beta Was this translation helpful? Give feedback.
-
|
Hi @kiwisincebirth, I somehow missed your entire post that included the comment about the ReadMe and the Introduction being so similar. Very sorry about that. I think we are in sync and will review your latest PR shortly. Thanks, Wayne |
Beta Was this translation helpful? Give feedback.
-
|
I am going to close this discussion as complete |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Observations
Ideas for reducing User Guide
Create a new "Hardware" document.
Create a new "Introduction" document
Other minor changes to User Guide
The point here is that user guide just becomes a How to Use - style of document - it shortens it to something more manageable, while adding a couple of new documents that can be extended latter.
Beta Was this translation helpful? Give feedback.
All reactions