docs
docs copied to clipboard
nunit
Style consistency: convert bold --> syntax style where necessary
While going through the docs I noticed that bold was used to connote technical references. We should switch that to syntax style instead.
To what extent should this be a general style choice versus a choice of the individual authors?
(I'm using "authors" in this case to mean the team members responsible for each major software component.)
IMO it should be consistent. Bold is for emphasis; back-ticks are for technical references.
Users should be able to have a consistent experience across the docs.
That's a reasonable view and I'd side with you if it were a matter of opinion. However, the individual projects decide and, in theory, could decide differently.
That's an interesting question from a governance perspective. My take would be that individual projects are welcome to host their own documentation, but to the extent they want to host it here, they'd want to follow the conventions (and we'll be reasonable about establishing those for sure.)
Might be worth discussing as an overall governance question in terms of where authority to make changes to docs ends for me. Good discussion to have clarity on
(I appreciate you raising these sorts of good questions! 👍 )
My view would be that you have pretty much full authority over how the documentation system works and almost none over the content. I see it that way because I think the individual projects are your clients. In the software world, we don't usually have "authority" over our clients. Instead we have to convince them of the benefit of doing things a certain way.
Admittedly, it's quite likely that nobody cares that much about this specific formatting issue. And there's an argument that formatting is really not the same as "content." Nevertheless, as a general principle I would lean toward asking rather than just deciding.
My personal thoughts: consistency is important, and that should be led by the docs project (I.e. Sean!) rather than the individual projects.
As a project-maintainer, I’d be quite happy for my contribution to be just the “words” - and the docs team standardise how it should be laid out etc. (Or course, in practice I expect that will be a more collaborative process than I’ve made it sound!)
@ChrisMaddock That's the sort of concurrence I thought @SeanKilleen should get from each project, and it was easy enough to get it from you. Basically, there are only five projects involved, with three different people (Chris, Rob and Mikkel) functioning as leads, so getting agreement should not be too much of a burden.
I really don't have any skin in this game since I don't have any docs here, but I had been encouraging Sean to work with the individual project leads as clients or users. So, for example, if one of you was really attached to the current use of bold then you ought to have a chance to say "No, don't change that, I did it for a reason!"
@SeanKilleen your use of the word "authority" probably triggered me a bit. As a lead you have complete authority over your project. But the other project leads have complete authority over theirs as well, so I guess collaboration is needed when it comes to the content of the docs.
Could you give the leads a few days to respond before changing how things have been done in the past? Our docs suggest 72 hours but you can accelerate that by knowing which people to check with and going direct.
Hi @CharliePoole,
I will do my best to accommodate this but there are things that are simply not correct currently, at least from a markup perspective. The more consensus we seek for minor changes that can be reverted easily afterward, the more we'll stagnate in this area. I mentioned previously my bias toward action. :) I'd prefer to make changes and then happily revert them should someone object.
This returns to the question of: what are the outcomes of the docs project that I am responsible for? If I want to make a change, in most cases, I will need to seek permission from someone else who "owns" an area, due to the nature of the docs project. I see myself as responsible for the successful outcome of NUnit's documentation overall, rather than just the docs build system.
Perhaps I should start a governance discussion laying out my overall vision for what the docs should be so that the project leads can weigh in on whether they agree? That might make the most sense to get some clarity on the kind of changes I'd expect my role to enable.
Overall, I of course have a great deal of respect for the team and anything they'd ask me to change I'd consider very important. But I want to balance that with moving forward at a rapid clip and having those conversations be reactive rather than preventative.
I think these goals will easily overlap -- I am concerned more with markup/formatting, display, layout, navigation, and the process to enable many more people to contribute to the docs.
I've written you separately (offline) about this very question at a bit more length.
So others know, I don't believe this is a governance (i.e. Core Team) issue. Of course, it would be if you tried to work things out with the leads of each project (four people) and were unsuccessful. Then you would have to bring it to the Core team. But the core team is just the same four people plus two more, so that's not a big deal.
According to our governance documentation, it would be a Core Team issue if you were asking to have the Core Team force the projects to do something they didn't want to do. But (a) I don't think that's what you are asking, (b) I don't think it's necessary and (c) I don't believe the Core Team would do that anyway.
I supported your your action orientation for getting this project live, but is it possible that it's time to take a beat and define the processes going forward? Although it's not a governance issue for the NUnit Project as a whole, it probably is one for your project. I do agree that laying out your vision is a good step. See my separate note for more details and let me know if I can help.
Sounds great, Charlie! I appreciate the note and I think you're right on next steps.
I don't mind the change and I also prefer consistency.
PS. I saw that you added backticks to the header in https://docs.nunit.org/articles/nunit-analyzers/NUnit1014.html. I'm unsure if I can make this change in the analyzers as this text is also used as a message in VS. One solution could be that I extend the analyzers, so it possible to specify a string for the messages in VS and another string used in the documentation. Or perhaps I'll just rephrase the title :)
@mikkelbu yeah, I was experimenting with that. I think in that case it would also be fine for us to add <!-- markdownlint-disable --> and the applicable rule number as well.
IIRC the linting issue was that markdownlint mistook <T> for html. So another solution could be to add an ignore pattern for that specifically, which would be fine with me too.
Any preferences on that? I think the heading is clear so I wouldn't want you to change it for doc formatting's sake if it messes things up elsewhere.
When emitting markdown docs, I think < and other special characters should be escaped as \< if not inside backticks. Backslash is standard markdown escaping. Would this solve the markdownlint issue?
@jnm2 I'll look into it locally and see if it's an option. Good suggestion!