Skip to content
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

Closed
10 tasks done
lread opened this issue Oct 1, 2023 · 1 comment
Closed
10 tasks done

doc: minor update reminders #348

lread opened this issue Oct 1, 2023 · 1 comment

Comments

@lread
Copy link
Contributor

lread commented Oct 1, 2023

From chat on Slack with @tengstrand:

I have wip in progress that conflicts with these secondary reviews. Hence this reminder issue.

Workspace

  • Replace: All techniques above still apply, but you will instead, for example:
    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

  • General -> Specific for:

Joakim: On the component page, I think we can leave out :extra-deps from "IDE Support for :local/root" because it's only :local-root that the IDEs have problem with
Lee: Technically true, I was just following the spirit of the original text. But I think this would be an improvement.
The content should would also need to be tweaked a tiny bit to state the general issue before moving on to the specific.

Example, Production Systems

  • In the tip at the top of example-systems, we could mention that the individual three diagrams in each image can be generated by the info, deps, and libs 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

  • The link "Different versions" does not work.

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.

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
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
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
@lread
Copy link
Contributor Author

lread commented Oct 9, 2023

All done!

@lread lread closed this as completed Oct 9, 2023
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
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant