Opened 5 years ago

Closed 5 years ago

#17509 closed enhancement (fixed)

Rephrase the front page of the developer's manual

Reported by: ncohen Owned by:
Priority: major Milestone: sage-6.5
Component: documentation Keywords:
Cc: jdemeyer Merged in:
Authors: Karl-Dieter Crisman, Nathann Cohen Reviewers: Karl-Dieter Crisman, Nathann Cohen
Report Upstream: N/A Work issues:
Branch: c4a8b8d (Commits) Commit: c4a8b8dd4986db015672aa445494965f8d6dd1ab
Dependencies: Stopgaps:

Description

The first page of the developer's manual is the one new contributors first meet when they want to write a patch. Our workflow is already confusing to many at first, so we should try to ease the pain.

The current page is available there: http://www.sagemath.org/doc/developer/

It gives useful information, but I thought that we could make it more efficient without losing any of it and while staying as welcoming.

With this branch, most of this introduction is rephrased/reduced. In particular the sentences which talk about what this document is about: this text appears before the table of contents, so it should be even more concise comparatively.

I tried not to lose any information. When I removed a link, it was because the link could be accessible through one hop (first go on the git page, then click somewhere else). As much as possible it would be nice to have the information in the relevant sections rather than on the front page, before the table of contents.

Tell me what you think,

Nathann

Change History (19)

comment:1 Changed 5 years ago by ncohen

  • Branch set to public/17509
  • Status changed from new to needs_review

comment:2 Changed 5 years ago by git

  • Commit set to e303ae6df03517cb09d06907406d0182284033a1

Branch pushed to git repo; I updated commit sha1. New commits:

e303ae6trac #17509: Rephrase the front page of the developer's manual

comment:3 follow-up: Changed 5 years ago by kcrisman

  • Cc jdemeyer added

Hi! I am not sure I agree with this, since the point of #17255 and its predecessors were to make this document less intimidating. For instance, the change

You are here because there is something in Sage that you want to change.

I think the whole point is that some people actually don't know whether there is something they want to change! And after all, one still has to read this guide to figure out how to get a Trac account to do something as simple as ask a question or report a typo... I think there is room for compromise, but several of us just spent a while updating this to be more verbose on purpose.

comment:4 in reply to: ↑ 3 Changed 5 years ago by ncohen

Hello !

Hi! I am not sure I agree with this, since the point of #17255 and its predecessors were to make this document less intimidating.

Oh. That was also *precisely* my aim. What I found intimidating in the current page is actuall the sheer length of the text. I thought that, at least for the front page, we could make it more factual (and stil friendly), while redirecting to the dedicated pages.

You are here because there is something in Sage that you want to change.

I think the whole point is that some people actually don't know whether there is something they want to change!

Funny. I was convinced that anybody who came to read the developer's manual was here because he wanted to actually change something. Would you prefer it rephrased in a different way, like "If you are here, you are about to learn how you can change Sage, be it documentation of code" ?

And after all, one still has to read this guide to figure out how to get a Trac account to do something as simple as ask a question or report a typo... I think there is room for compromise, but several of us just spent a while updating this to be more verbose on purpose.

Well, then let us have this discussion here, it is the purpose of trac tickets !

1) What would you say that I lost by making this text shorter ? I tried to keep as much information as possible, and to remain "welcoming". Can you tell me something that would have made it "less impressive" to newcomers in the current version, and that is not here anymore ?

2) Initially I only wanted to make the current text easier to 'scan through'. To find information quickly. I do not know about your screen, but when I display the current page I do not even see the table of contents below. If I want to find some information, the first thing I do is read the text, and that it not exactly done with a quick glance. Hence the bold fonts, hence less items.

I am all ears. You want to make it less intimating, I want to make it les intimidating, so first we have to understand why we both think that our version is okay while the other's is 'too indimidating' :-P

Nathann

comment:5 follow-up: Changed 5 years ago by kcrisman

I think that we agree in general, actually. If we could use javascript to just fold the explanations away it would be ideal, but we won't. Here's a possible proposal.

  • Keep the beginning material. It's really useful to start right off suggesting the ways one can contribute.
    Everybody who uses Sage is encouraged to contribute something back to
    Sage at some point. You could:
    
    * Add examples to the documentation
    <snip>
    documentation. We also discuss how to share your new and modified code
    with other Sage users around the globe.
    
  • Then something like, "Here is a brief outline of the sections of this guide. Skip to here (provide section link) for longer outlines of what each section contains."
  • Then your descriptions, possibly even shorter than they are there.
    - **Trac server:** all changes go through the `the Sage Trac server
      <http://trac.sagemath.org>`_ at some point. It contains bug reports, patches
    
  • Then the longer descriptions.

So I agree that shorter can be very helpful, but not at the expense of not really explaining anything. I think it's really important to have the initial material give enough info for someone brand-new (just been corresponding with someone, in fact, not a mathematician) know where they should go for their own first needs. The real problem is just that the developer guide is long!

But there is no way to avoid that, because we want it to be pretty comprehensive, if only to forestall mistakes or sage-devel emails.

comment:6 in reply to: ↑ 5 Changed 5 years ago by ncohen

Helloooooo !

Okayokay, I will try to rephrase it today and give you another version in the evening. I have a problem at the university though, there is a proxy there and I cannot use git at all. Even posting a comment on a trac ticket takes minutes (per comment) ^^;

I think that we agree in general, actually. If we could use javascript to just fold the explanations away it would be ideal, but we won't.

You do not think that html links do the job ? That's how I was thinking about these things: "I add links and the info will be on the corresponding pages, if the guy is interested he will click there". So a bit like how you would like to fold things.

Here's a possible proposal.

  • Keep the beginning material. It's really useful to start right off suggesting the ways one can contribute.

Could you tell me how you picture the user who gets there to be ? I mean. I thought he would be a guy who was redirected there by someone saying "Hey, Sage is open source so if you do not like this you should learn how to change it" but you tell me that some users do not actually have this in mind. Who do you think this document is meant for ? It will help me rephrase it in a way that you like better.

  • Then the longer descriptions.

By 'the longer descriptions' what do you mean ? Those from the current version ? Those from my version (that you tell me to make even shorter) ? Let us not forget that the table of contents follows immediately after !

So I agree that shorter can be very helpful, but not at the expense of not really explaining anything. I think it's really important to have the initial material give enough info for someone brand-new (just been corresponding with someone, in fact, not a mathematician) know where they should go for their own first needs.

Would you prefer something like that ?

1) Before anything, ask for a trac account (takes from 1h to a couple of days) 2) Then, compile Sage. It can also take some time (takes several hours) 3) Now you have time to read this guide

But there is no way to avoid that, because we want it to be pretty comprehensive, if only to forestall mistakes or sage-devel emails.

We do have to say everything, but not all at once :-)

Nathann

comment:7 Changed 5 years ago by kcrisman

Could you tell me how you picture the user who gets there to be ?

Any Sage user. We want to convince them that they should become 'developers' (in the sense of making some contribution, even reporting a bug). The table of contents is far too overwhelming. I figure anyone who actually knows something will do a tl;dr and skip to the TOC, you are right. But they certainly don't have to compile Sage or read the whole guide; the idea I have is to have enough at the top for them to know really what part they even want to read!

comment:8 follow-up: Changed 5 years ago by ncohen

I see. What I had in mind was more something like "a reference manual for developpers", i.e. a document that mostly contains technical information. But you are right, this probably isn't how we want the first-time developers to read this manual or they will be lost immediately.

What do you think of something in between ? We could have a page for first-time contributors, and link toward it right at the top of the developer's manual ?

Something like: "If you never contributed to Sage, you want to click here" (or anything you might prefer to that) ?

Then on this page we can be as slow and caring as we want, and link wherever we need.

What do you think ? Really my main objection to the text is its location and length. If we move it to a different page with a clear link meant for first-time developers then the table of contents becomes visible and all and I have no problem with that.

We could also use this branch to do both: 1) move the current text to a new page meant for newcomers 2) add a link toward this page in the first line of the index 3) Leave some more concise (and still more human than a table of contents) introduction to what's next (a bit like what the current branch contains)

Again, please tell me what you think !

Nathann

comment:9 in reply to: ↑ 8 Changed 5 years ago by jdemeyer

Replying to ncohen:

Really my main objection to the text is its location and length.

Does it really bother you so much that you need to scroll down a page to see the actual table of contents?

comment:10 follow-up: Changed 5 years ago by ncohen

Does it really bother you so much that you need to scroll down a page to see the actual table of contents?

Jeroen, sorry for asking but have I done something bad to you recently ?

I am just trying to make this page clearer. I loaded it once and thought that it was much too heavy, so I tried to make it lighter to read, more 'concise'. Then Karl-Dieter told me for which kind of reader he had written it like that, and so we try to make it work at the same time for the readers that Karl-Dieter has in mind (users who are about to become developpers), and for those that I have in mind (guys who just need a factual information).

There isn't any problem, actually. We talk, we try to see what we missed by asking the other how he would like it to be, and eventually we will update the page.... No worries.

Nathann

comment:11 Changed 5 years ago by ncohen

Also, what would you think of decrementing the depth of the table of contents on that page ?

Nathann

comment:12 in reply to: ↑ 10 Changed 5 years ago by jdemeyer

Replying to ncohen:

Does it really bother you so much that you need to scroll down a page to see the actual table of contents?

Jeroen, sorry for asking but have I done something bad to you recently ?

No, no. There is absolutely nothing personal. My question was just meant to ask for clarification. Maybe I should have asked "Why does it bother you so much..."

comment:13 follow-up: Changed 5 years ago by kcrisman

Here is a concrete proposal.

Everybody who uses Sage is encouraged to contribute something back to
Sage at some point. You could:

* Add examples to the documentation
* Find bugs or typos
* Fix a bug
* Implement a new function
* Contribute a useful tutorial for a mathematical topic
* Translate an existing document to a new language
* Create a new class, create a fast new C library, etc.

This document tells you what you need to know to do all the above,
from reporting bugs to modifying and extending Sage and its documentation.
We also discuss how to share your new and modified code
with other Sage users around the globe.

Here are brief overviews of each part; for more details, see
the extended table of contents below.
No matter where you start, good luck and welcome to Sage development!

- **Trac server:** all changes go through the `the Sage Trac server
  <http://trac.sagemath.org>`_ at some point. It contains bug reports, upgrade
  requests, changes in progress, and those already part of Sage today. :ref:`Click here
  <chapter-sage-trac>` for more information.

  Importantly, you will need to :ref:`create a trac account <section-trac-account>`
  in order to contribute.

- **Source code:** You need your own copy of Sage's source code to change it.
  `Go there <http://www.sagemath.org/doc/installation/source.html>`_ to get it
  and for instructions to build it.

  If you have never worked on software before, pay close attention to the
  `prerequisites to compile <http://www.sagemath.org/doc/installation/source.html#prerequisites>`_
  on your system.

- **Conventions:** read our :ref:`conventions and guidelines
  <section-writing-code-for-sage>` for code and documentation.

  For everything related to manuals, tutorials, and languages, :ref:`click here
  <chapter-sage_manuals>`

- **Git (revision control):** To share changes with the Sage community, you will
  need to learn about revision control; we use the software Git for this purpose.
 
  - :ref:`Here is <chapter-walkthrough>` an overview of our development flow.
  - :ref:`Unfamiliar with Git or revision control ? <chapter-git_trac>`
  - :ref:`How to install it ? <section-git-install>`
  - :ref:`How to configure it for use with Trac ? <section-git-setup-name>`
  - :ref:`The dev scripts <chapter-devscript>` may be used without installing git,
    but are only intended as a bridge to using it properly.

I think you are right that the previous was a bit verbose, but I think I was right that it's no problem to scroll slightly to see all of this overview.

comment:14 in reply to: ↑ 13 Changed 5 years ago by ncohen

  • Authors set to Karl-Dieter Crisman, Nathann Cohen
  • Reviewers set to Karl-Dieter Crisman, Nathann Cohen
  • Status changed from needs_review to positive_review

Yoooooooooooo !

Here is a concrete proposal.

Okay, workd for me. I compiled it, and with this it takes half a second for somebody like me to understand that there is nothing here that I should read, and that I can scroll down. I hope that I would do the same even if I did not know that there is a table of contents below.

I updated the branch. I have no problem at all with it, except for the "importantly". I never saw a sentence begin with "Importantly" (it was always "More importantly"), but I think I can trust your judgement better than mine on this point.

I think you are right that the previous was a bit verbose, but I think I was right that it's no problem to scroll slightly to see all of this overview.

Well, you do scroll if you know that there is something else to find below. Anyway, this can totally do for the moment and there are probably others places in the developer's manual that need to be reorganized. From a look at the table of contents it seems that 75% of what we do is explain how to use git :-P

Good to go !

Nathann

comment:15 Changed 5 years ago by git

  • Commit changed from e303ae6df03517cb09d06907406d0182284033a1 to a3569420d71cb00af1288d575fd8f97f186936d8
  • Status changed from positive_review to needs_review

Branch pushed to git repo; I updated commit sha1 and set ticket back to needs_review. This was a forced push. New commits:

a356942trac #17509: Rephrase the front page of the developer's manual

comment:16 Changed 5 years ago by kcrisman

This was something you missed that I didn't fix in my comment, my apologies. Do this and set to positive review.

-  <chapter-sage_manuals>`
+  <chapter-sage_manuals>` .

It really looks great, and I think the net result is definitely an improvement that is still very welcoming.

Last edited 5 years ago by kcrisman (previous) (diff)

comment:17 Changed 5 years ago by git

  • Commit changed from a3569420d71cb00af1288d575fd8f97f186936d8 to c4a8b8dd4986db015672aa445494965f8d6dd1ab

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

98e29d6trac #17509: Rephrase the front page of the developer's manual
c4a8b8dtrac #17509: THE missing dot.

comment:18 Changed 5 years ago by ncohen

  • Status changed from needs_review to positive_review

Heeeeeere it is. I added the missing dot and discretely rebased it all on top of the latest beta.

Thanks for your help !

Btw, I may write another 'developper commit' over the weekend.. Depends on how fast I will finish my slideshow for tuesday T_T

Good evening,

Nathann

comment:19 Changed 5 years ago by vbraun

  • Branch changed from public/17509 to c4a8b8dd4986db015672aa445494965f8d6dd1ab
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.