-
-
Notifications
You must be signed in to change notification settings - Fork 49
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: minor update reminders #348
Comments
lread
added a commit
to lread/polylith
that referenced
this issue
Oct 6, 2023
Todo from polyfy#348 (also trailing whitespace trim, apparently I did not have trim trailing whitespace setup in VSCode for my first edit)
lread
added a commit
to lread/polylith
that referenced
this issue
Oct 6, 2023
lread
added a commit
to lread/polylith
that referenced
this issue
Oct 6, 2023
lread
added a commit
to lread/polylith
that referenced
this issue
Oct 6, 2023
lread
added a commit
to lread/polylith
that referenced
this issue
Oct 6, 2023
Add notes on doc diagrams and SNAPSHOT releases. Felt doc would benefit from a table of contents, so added one. Todo from polyfy#348
Closed
lread
added a commit
to lread/polylith
that referenced
this issue
Oct 6, 2023
Should be local preview and cljdoc.org friendly now. Todo from polyfy#348
This was referenced Oct 6, 2023
Merged
tengstrand
pushed a commit
that referenced
this issue
Oct 7, 2023
Add notes on doc diagrams and SNAPSHOT releases. Felt doc would benefit from a table of contents, so added one. Todo from #348
tengstrand
pushed a commit
that referenced
this issue
Oct 7, 2023
Should be local preview and cljdoc.org friendly now. Todo from #348
tengstrand
pushed a commit
that referenced
this issue
Oct 7, 2023
tengstrand
pushed a commit
that referenced
this issue
Oct 7, 2023
tengstrand
pushed a commit
that referenced
this issue
Oct 7, 2023
Todo from #348 (also trailing whitespace trim, apparently I did not have trim trailing whitespace setup in VSCode for my first edit)
tengstrand
added a commit
that referenced
this issue
Oct 7, 2023
* docs: dev doc todos (#361) Add notes on doc diagrams and SNAPSHOT releases. Felt doc would benefit from a table of contents, so added one. Todo from #348 * docs: fix cljdoc versions link (#360) Should be local preview and cljdoc.org friendly now. Todo from #348 * docs: mention commands used in system docs tips (#357) Todo from #348 * docs: Generalize discussion on local/root deps (#356) Todo from #348 * Rephrase sentence in Workspace doc (#355) Todo from #348 (also trailing whitespace trim, apparently I did not have trim trailing whitespace setup in VSCode for my first edit) * Updated snapshot version to #4. --------- Co-authored-by: Lee Read <[email protected]>
lread
added a commit
to lread/polylith
that referenced
this issue
Oct 8, 2023
Kinda a subtle one Joakim and I came up with, but here it is! Mention docs should be written in a casual and friendly tone in the dev doc. Change occurrences of "do not" to "don't". Todo from polyfy#348
lread
added a commit
to lread/polylith
that referenced
this issue
Oct 8, 2023
Did not apply callouts to workspace file/directory tree block. Because there would be so many of them, they made the content less readable. Instead tweaked existing inline comments for clarity. Todo from polyfy#348
lread
added a commit
to lread/polylith
that referenced
this issue
Oct 8, 2023
NOTE: Also renamed :parameters to :arglists in doc code blocks. @tengstrand will follow up with appropriate code changes. Did a sweep of all docs to make this change. Some doc changes were in help component. Rebuilt poly and ran ./update-commands-doc.sh from ./script dir to regenerate doc/commands.adoc Todo from polyfy#348
lread
added a commit
to lread/polylith
that referenced
this issue
Oct 8, 2023
The reader might not be going through docs sequentially, so always mention that examples are part of a tutorial and give an idea of where they are in that tutorial. Updated docs that I had already reviewed, will update subsequent docs appropriately as I review them. Todo from polyfy#348
lread
added a commit
to lread/polylith
that referenced
this issue
Oct 8, 2023
The reader might not be going through docs sequentially, so always mention that examples are part of a tutorial and give an idea of where they are in that tutorial. Updated docs that I had already reviewed, will update subsequent docs appropriately as I review them. Todo from polyfy#348
tengstrand
pushed a commit
that referenced
this issue
Oct 9, 2023
* docs: use casual tone Kinda a subtle one Joakim and I came up with, but here it is! Mention docs should be written in a casual and friendly tone in the dev doc. Change occurrences of "do not" to "don't". Todo from #348 * Add code block callouts to reviewed docs Did not apply callouts to workspace file/directory tree block. Because there would be so many of them, they made the content less readable. Instead tweaked existing inline comments for clarity. Todo from #348 * Docs now use "argument" instead of "parameter" NOTE: Also renamed :parameters to :arglists in doc code blocks. @tengstrand will follow up with appropriate code changes. Did a sweep of all docs to make this change. Some doc changes were in help component. Rebuilt poly and ran ./update-commands-doc.sh from ./script dir to regenerate doc/commands.adoc Todo from #348 * Mention tutorial throughout docs The reader might not be going through docs sequentially, so always mention that examples are part of a tutorial and give an idea of where they are in that tutorial. Updated docs that I had already reviewed, will update subsequent docs appropriately as I review them. Todo from #348
All done! |
tengstrand
added a commit
that referenced
this issue
Oct 9, 2023
* Fixed typo. * readme: tweak wip note (#363) Remove instructions on how to get poly version. Joakim and I felt it might be more confusing than helpful at this very early point in the docs. * Added link to the final code example. * introduction doc: tutorial concept (#364) Add concept that code examples provide an ongoing tutorial. This should now provide something we can link back to from other docs that include tutorial code examples. Tried to make minimal changes as I know Joakim wants to maintain a specific tone to the introduction. Fix link to end result of tutorial so that it links back to GitHub released revision. * Remaining doc todos sweep (#365) * docs: use casual tone Kinda a subtle one Joakim and I came up with, but here it is! Mention docs should be written in a casual and friendly tone in the dev doc. Change occurrences of "do not" to "don't". Todo from #348 * Add code block callouts to reviewed docs Did not apply callouts to workspace file/directory tree block. Because there would be so many of them, they made the content less readable. Instead tweaked existing inline comments for clarity. Todo from #348 * Docs now use "argument" instead of "parameter" NOTE: Also renamed :parameters to :arglists in doc code blocks. @tengstrand will follow up with appropriate code changes. Did a sweep of all docs to make this change. Some doc changes were in help component. Rebuilt poly and ran ./update-commands-doc.sh from ./script dir to regenerate doc/commands.adoc Todo from #348 * Mention tutorial throughout docs The reader might not be going through docs sequentially, so always mention that examples are part of a tutorial and give an idea of where they are in that tutorial. Updated docs that I had already reviewed, will update subsequent docs appropriately as I review them. Todo from #348 * Rename from parameter to argument (work in progress) * Replace :parameters with arglist in interfaces:definitions:DEFINITION:arglist. * Bumped to snapshot #5. * Use default deps.edn content when reading old :toolsdeps workspaces (that lack deps.edn files per brick). Fixed a bug in polylith.clj.core.lib.core/lib->deps. Executed create-example.sh. * Remove unused namespace. * Updated output from "doc page:". * Fixed failing tests. * Bumped libraries. --------- Co-authored-by: Lee Read <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
From chat on Slack with @tengstrand:
I have wip in progress that conflicts with these secondary reviews. Hence this reminder issue.
Workspace
With: All techniques above still apply, but you will instead create a workspace like so:
(With the idea it will probably be easier to grok for folks whose first language is not English.)
Component
Example, Production Systems
info
,deps
, andlibs
commands that we will cover later.Dev docs
Mention InkScape is used for doc diagrams.
Convention of saving .svg next to .png.
Use cross-platform fonts (I think installing Microsoft fonts should be enough).
Mention SNAPSHOT check behavior.
Doc
General
do not -> don't
We'll prefer don't in general. Might also add note to dev docs on docs.
We've decided on "argument" instead of "parameter". I'll swing back to documents I've already edited and make the change, otherwise I'll handle this as I progress sequentially through docs.
Add (1), (2)...numbering (adoc code callouts) to the code examples in already reviewed pages, like near "Your workspace directory structure" and "Let’s listen to the helpful reminder" in component.adoc.
Describe the tutorial example in some detail very early in the docs.
Then we can link back to that description from later tips.
The text was updated successfully, but these errors were encountered: