Overhaul README and documentation catalog to introduce best practices#363
Conversation
FranzBusch
force-pushed
the
fb-readme-doc-overhaul
branch
from
3db3c66 to
0ac66ff
Compare
ktoso
left a comment
ktoso
left a comment
There was a problem hiding this comment.
Looks good overall, some suggestions inline.
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
|
Shouldn't we keep the section about implementing a Line 153 in 81d3d07 |
|
@sebsto I have another document that moves this into a guide. You mind if I land this in a follow-up? |
|
@FranzBusch Great ! I just wanted to be sure it's not forgotten |
FranzBusch
force-pushed
the
fb-readme-doc-overhaul
branch
2 times, most recently
from
d72cf2c to
2ae3e90
Compare
heckj
left a comment
heckj
left a comment
There was a problem hiding this comment.
a few grammar tweaks - removing latin abbreviations, spelling out an acronym, and making some of the wording more direct.
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
FranzBusch
force-pushed
the
fb-readme-doc-overhaul
branch
from
2ae3e90 to
15c3584
Compare
heckj
left a comment
heckj
left a comment
There was a problem hiding this comment.
The top level page for swift-docs is pretty long - it may benefit from breaking up into separate articles on getting started and core concepts, but I don't think that's critically needed for this update.
I went back with my fine-toothed comb and suggested some punctuation, grammar, and style fixes - and restricting the best practices page to use ## Topics to make it a page that explicitly links to others (aka API Topic Reference page) to hold the best practices without a lot of extra redundancy.
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
Sources/Logging/Docs.docc/Best practices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
czechboy0
left a comment
czechboy0
left a comment
There was a problem hiding this comment.
A few comments, looks great otherwise!
FranzBusch
force-pushed
the
fb-readme-doc-overhaul
branch
2 times, most recently
from
0ac334b to
3ac92c6
Compare
FranzBusch
force-pushed
the
fb-readme-doc-overhaul
branch
2 times, most recently
from
25106b1 to
929bce2
Compare
tib
left a comment
tib
left a comment
There was a problem hiding this comment.
The changes look good. I like that you have included practical examples of both good and bad practices.
Sources/Logging/Docs.docc/BestPractices/001-ChoosingLogLevels.md
Outdated
Show resolved
Hide resolved
# Motivation `SwiftLog` was created before DocC existed which meant that most of the documentation was part of the `README` and we had a pretty bare bones documentation catalog. We also have a second source of guidelines from the SSWG. This results in a currently unsatisfying developer experience where everyone has to go around looking for the content in mostly undocumented places. # Modifications This PR overhauls the `README` and moves most of the content into the documentation catalog. It also introduces a new section called "Best practices" that are intended to replace the logging guides on swift.org so that the content moves closer to where it belongs. To showcase such a best practice this PR brings over the log level recommendation of swift.org. The recommendation is mostly the same except that after recent discussions we wanted to allow libraries to log at `info` level when they encounter problems which they can't communicate through other channels e.g. by throwing from a method. # Result With this PR we provide a nicer experience to our developers making it easier for them to get started and understand how to properly log. We also set ourselves up for expanding on the best practices around logging.
FranzBusch
force-pushed
the
fb-readme-doc-overhaul
branch
from
929bce2 to
8908b0d
Compare
7 participants
Motivation
SwiftLogwas created before DocC existed which meant that most of the documentation was part of theREADMEand we had a pretty bare bones documentation catalog. We also have a second source of guidelines from the SSWG. This results in a currently unsatisfying developer experience where everyone has to go around looking for the content in mostly undocumented places.Modifications
This PR overhauls the
READMEand moves most of the content into the documentation catalog. It also introduces a new section called "Best practices" that are intended to replace the logging guides on swift.org so that the content moves closer to where it belongs. To showcase such a best practice this PR brings over the log level recommendation of swift.org. The recommendation is mostly the same except that after recent discussions we wanted to allow libraries to log atinfolevel when they encounter problems which they can't communicate through other channels e.g. by throwing from a method.Result
With this PR we provide a nicer experience to our developers making it easier for them to get started and understand how to properly log. We also set ourselves up for expanding on the best practices around logging.