Underlining the page headings

[smolinari]

Hi,

I've been adding an

---

(4 underlines) under the page headings, but now just noticed it conflicts with the underline already added in the CSS.

I like the thicker underline. However, what to do about this? I can understand wanting the design in the CSS, so I guess the way to go is to fix my added underlines. Just wanted to make note of that, when the next PR comes in, so nobody faints at all the changes and wonders WTF is Scott doing. LOL! 😄

I'll have to come up with another way to note I've done work on the file. Does the ODB docs system or gitbook allow for hidden comments in the markdown?

Hehe...maybe just an HTML comment?

Scott

[kennethpjdyer]

@smolinari Definitely an issue with the headings in that there's not enough distinction between the different levels. But, you're right, manual approach is bad. Too much work to implement and maintain and it adds another thing for people to watch for on pull requests.

We actually have a better solution in place. When GitBook runs it adds css/custom.css to the output. So any formatting adjustments made there carry over into the webpage. Right now the only thing in there is the userinput class formatting for code blocks. So, there's plenty room for you to get creative.

For comments, use the GitHub web interface on your pull requests. That'll create something we can see and won't leave any baggage on the files.

[smolinari]

Thanks Kenneth, however, you lost me on the comments. 😄

What is needed is a per file inline comment, which notes that the file was proofread. Anyone updating the file in any editor should be able to see the comment. If they edit the file, they should remove the proofread comment and, they should note what they changed for the proofreader(s) (in a comment). This is a typical editing process. In fact, in ODB's situation, there should be two proofreaders, if the person writing isn't an ODB technical team member. One proofreader to check the content for technical correctness and another for the grammatical correctness. I'm not totally knowledgeable about ODB and have found a couple technical mistakes in the docs. They seemed simply mistakes though. Still, that puts the whole content of the docs in question on technical correctness. This part of the quality of the docs should not be underestimated.

I believe, to go through the files in the github web interface to find editing stage/process information like that would be a bit of a problem. Or, I am not understanding what you mean.

Scott

[kennethpjdyer]

Might’ve misunderstood what you were after in the first, thought you meant more in an explain what you're doing kind of way.

I’ve no objection to making the technical reviews more formal. The method you’re suggesting would remove the one click approval on pull requests, but maybe that’s okay? Alternatively, we could keep relying on users to tell us when things outright don't work. In any event, a change like that would require organization on the company-side for whichever devs get charged with reviewing pull requests and whether they want to undertake it at this point in time. What do you think, @lvca?

Insofar as proofreading for editorial issues, grammar, language and so on, we can manage that kind of thing better outside the pull request system. Pull requests only cover changes coming from outside the company and editorial would need to review everything in order for it to work effectively. I'll look into ways to manage it later this week over turkey.

--Kenneth

[smolinari]

Ok. I've corrected the underlines. New PR is up.

I've also added an HTML comment on all the files I've proofread, so I can keep track of them. This could be a standard process step for the docs. But, not only for me proofreading, but anyone who does, should update the comment.

And, if someone adds any large bits of text and isn't sure about the grammatical correctness, they can remove the date and initials in the comment and request a review.

At any rate. I'd like to have the comment, even though I am going top-down through the docs, just so I know what is proofread. Maybe someone else will join in on the fun. Then we won't be doing double work.

I hope it is ok (and the comments work on the live site too).

Scott

[smolinari]

Oh, I also added the underline as I think it should be in the custom.css. Looks simply better being a bit thicker IMHO.

https://smolinari.gitbooks.io/orientdb-documentation/content/v/57a590f9e45e733ffcdcf4324dd032de0b98f00f/

Scott

[lvca]

@smolinari I see the docs on your website doesn't suffer of the nasty 2-steps loading effect I notice when I click on any page on the orientdb website. Do you have any idea why? Or this is something I only see?

[smolinari]

A couple of times I've also noticed the 2-step loading on the odb.com site. I think it is relevant to how that docs are being served, maybe something slowing the server down in retrieving the JS? How the JS is loaded?

"My website" is Gitbook.com and I have no idea what the differences from odb.com and Gitbook.com might be.

Scott

[santo-it]

Hi,

I think this is old and can now be closed. Scott's feedback about using an html comment about proofreading is cited already in Issue #90

Please reopen if needed

Thanks!