Consider adding "Edit on Github" to developer reference

[icook]

First I wanted to say I really like the new dev docs. I really wish it existed when I started reading about bitcoin dev.

I enjoy contributing to docs like these when possible, but I've found I'm much more likely to do so if there's an easy link back to the actual file that generated the page. Would you accept a pull request if I added this?

[saivann]

@icook Thanks!

Do you have an idea how you would implement this? (Taking into account that each page is build using several files). As far as I'm concerned, I like the idea but I guess this depends how it's implemented (and if this feature creates other issues).

Otherwise maybe a simple "Participate" link in the menu pointing to the relevant README text https://github.com/bitcoin/bitcoin.org#developer-documentation would do?

FWIW, the "Report An Issue" link already lets people report an issue and suggest improvements while automagically inserting a contextual link to the relevant subsection in the GitHub issue.

[harding]

@icook thanks for the complement!

A possible idea would be to have a "[edit]" link next to each section (H2) title similar to what MediaWiki does. Manually adding a link for each section which points to the appropriate file would be pretty easy, and we could probably point it to the edit interface on GitHub for quick edits.

[saivann]

I just tested to see what a visitor who knows nothing about GitHub and didn't already have forked the repository would have to deal with by visiting a sample "Edit this page" link (https://github.com/bitcoin/bitcoin.org/edit/master/_includes/guide_contracts.md). After creating an account, I was positively surprised, GitHub seems to make it simplier than I thought (see screenshot below).

[icook]

It looks like Jekyll might already have it covered: Ctrl+F page.path here. I'm not super familiar with Jekyll, but seems doable.

For styling I was thinking something in the vein of Readthedocs on the top right. It would be cool to jump to a specific section, but I'm not sure on the Github support for that.

[saivann]

@icook This would need testing, but I think page.path will only return the .html page, not the actual markdown files used to produce the page. As for the layout, I guess we don't have choice but to contextually link to specific subsections because the content is split in many files.

There is the MediaWiki-like option like what @harding suggested, or if the idea sounds good, I can provide the javascript to add a link in the table of content that would work like the current "Report An Issue" link, so long as we put enough information on the page (e.g. data-sourcefile="data" attribute near the titles) that javascript can use to find the source file associated with the current subsection.

[harding]

@saivann Nice! I hadn't thought about how hard it might be for new GitHub users.

A javascript-updated link would be much better because we have one case (the RPC docs) where a single section is split across multiple files (ref_core_rpcs-*).

While we're at it, it might be nice to move the meta options over the top of the table of contents so they're always visible. For example ([X] is an icon):

[←] Overview | [!] Issue | [E] Edit
-----------------------------------------
Block Chain
    ....
Transactions
.....

The top links would have tooltips with expanded descriptions.

[icook]

@harding I like it. Makes it more clear that these aren't other content pages.

@saivann I went ahead and gave it a shot and page.path does link to the markdown, but it always references the top level template, so it's not very helpful in include heavy documents. I dug through the Jekyll code a bit but there's no way to get reference to the include being rendered. Looks like a two line change, but may be more work than it's worth trying to get it merged to Jekyll. Javascript sounds good to me.
icook/bitcoin.org@23500ec

[saivann]

@icook @harding Here's one way of doing it (icon missing and commit a bit poorly tested):
8a8c814

Live preview:
http://bitcointest2.us.to/en/developer-guide

@harding I like your suggested layout too!

@icook if you have time to play with CSS/HTML/Javascript and see if you can make it always always visible, you're welcome! Otherwise I may have time to try it later. I don't know how easy it will be - the toc should gracefully adjust positioning and size while scrolling at the top, middle and bottom of the page, with content that sometimes require a scrollbar, sometimes not.

[harding]

@saivann nice! Basic testing all looked good to me. How about a plus-minus for the symbol, like the unicode ± (U177 in the basic latin1 range)? I think that's pretty much the universal symbol for revision control, which seem applicable here.

(And GitHub's edit interface seems to have improved since I last used it, making editing easier for markdown novices.)

[icook]

@harding ± sounds good, otherwise probably an icon similar to fontawesome's Github specific symbol.

@saivann Looks great! I can probably add a proper icon tomorrow. Not sure what you meant by showing up all the time? My brief look at it seemed to be fine minus the icon.

[saivann]

@icook I just added a ± icon I had made previously today to the branch and updated the live preview (just so we don't duplicate effort, unless you think you can provide something better);
764037a

The fontawesome icon I think is cool and probably more friendly, however by making our own icon we can avoid the hassle that comes with inserting content with various licenses in the same directory.

My understanding of @harding's comment is he suggested we could have this moved at the top of the toc (table of contents) and stylize the toc to make sure it always remain visible like a toolbox. Currently, if you visit a long toc like the Bitcoin Core RPC (http://bitcointest2.us.to/en/developer-reference#getaddressesbyaccount), you'll see that these buttons are not visible. There's probably a way to avoid this issue. I'm not sure though if this toolbox would interfere too much with the content if moved at the top, personally, I tend to think it's more appropriate at the bottom of the screen.

[harding]

In my opinion, the current version looks good enough for a pull request. Thanks @saivann for the work and @icook for the idea!

To clarify my earlier comment, I would like (wishlist) a one-line high, always-visible toolbox with the overview, issue, and edit links. I have no preference for where the toolbox appears on the page, and hiding it on mobile layouts seems fine to me. If implementing it will be difficult with the current layout, I suggest we just add it as a comment to issue #596 as an idea for a future redesign of the docs layout.

[saivann]

Pull req -> done.

TBH, I think making a fixed-position always visible toolbox might either be super simple, or need to rewrite a moderate chunk of CSS, HTML and javascript. @icook Please let me know if you're interested to work on it. I should be around if you have any issues or questions.

[saivann]

I forgot to say, I think this is a great idea for inviting new contributors, thanks @icook and @harding!

[icook]

@saivann I'm probably good for now. I'll be trying to make some docs PRs occasionlly tho!

[saivann]

@icook Very appreciated, thanks!!