>> Hi, everyone. I'm Atin Bansal,
and today I'll be talking to you about the VSTS Wiki.
Unfortunately Sandeep was not able to join us.
He's the VSTS Wiki owner.
But you can contact either of us on the Twitter handles
listed here for any feedback or questions that you have.
Before I jump into the demo,
I want to talk about why we created VSTS Wiki.
We wanted to make it really easy for teams to create,
process, project,
and develop documentation in a very simplified manner.
Let's also talk about the three underlying technologies
that help us create VSTS Wiki, first being GIT.
GIT is a technology that is used worldwide
for millions of source control repositories,
and that's the backing of VSTS Wiki as well.
The second is Markdown.
Markdown has become our documentation standard
across multiple platforms,
and that is what we use in VSTS Wiki.
The third one is Elastic Search,
which gives us the power to index everything
that you put into the Wiki and make it discoverable.
So let's go into the demo.
For the demo, I'll be using two personas,
John, who is a business analyst,
and Jessica, who is a developer.
John wants simplified yet rich experiences
for his documentation.
However, Jessica, who is a co-developer,
wants something that she's very familiar with.
She doesn't want to come out into
a separate space to do her documentation.
She wants something which aligns with what she uses,
which is ID most of the time,
supports workflows that she's used to,
and is able to cater to
her API and SDK documentation needs.
One other need that both John and
Jessica have is Ubiquitous discovery.
They both want the documentation that they
write to be discovered by everybody else.
So let's see how VSTS Wiki enables you to do this.
We'll start over John's persona.
I'll move forward to my demo project,
and assume that John comes and clicks on this Wiki tab,
he sees two CDS: create Wiki,
and publish code as Wiki.
We'll come to publish code as Wiki later.
Let's just go ahead and click on Create wiki for now.
What happened in the background here is that
a GIT repo got provision for this Wiki.
However, John is totally oblivious to that.
He sees a nice page,
we're just calling him to put in a page title.
So let's put in a page title called "My First
Page," and save it, and let's close this.
As you can see, the page has been created,
and it shows up on the right hand side,
and sort of like a table of contents that will
be build up automatically for you.
Let's create a new page now.
So, I want to quickly talk about what
are the capabilities of Wiki that we provide.
Obviously, you can start using
the normal Markdown's syntax, if I can spell right.
But as you can see, we actually have a live preview pin.
Anything you write here shows up
here with how it would actually look to the end user.
Now, I feel this is a pretty great thing because,
otherwise what I have to do is,
I have to type something and hope that it's right,
and then save it,
click on preview in some other place,
and actually see it and then say,
"This doesn't look good, let me go back and do it again."
However, here, you are actually able to
change things right away,
because you're able to see it on the right hand side.
So, let's assume that we are creating
a Wiki page and we want to link
it to some other page in the Wiki.
Here at the top, we have
quick shortcuts that you can use.
So, I'll quickly use the shortcut and I'll say " Link
to first page," so you can type,
and then as soon as they come into the actual page,
VSTS Wiki shows you all the pages in the Wiki,
and you can search and find
the page that you're looking for and link it.
Now, I can also link
the same thing by doing the notation myself,
and again I get the same power of search to find
the page and link the page.
Or, I could have gone to my table of contents,
and dragged and drop the page here,
and it will still create a link for
you as you can see on the right hand side.
So, what else other than
links that we put into the Wiki pages?
Definitely, pictures are something that
I like to put in my Wiki pages.
However, I think pictures to
a GIT repository is very hard.
I have to take a snap,
I have to save it to disk,
I have to upload it to my GIT repo,
and then reference it from my Markdown page.
In VSTS Wiki, it's much simpler.
So, assume that this is a page
that you want to take a snap off,
I just do a new in my snap tool,
pick a snap, come here "Control V, " and done.
I have the link to the image here,
and I have the actual preview of
the image right here on the page.
Few seconds, that's it.
Also with the power of Gatwick's,
we have brought in
mathematical formulas supposed to Wiki.
So, I can simply do E equals MC Square,
and as you can see on the right hand side,
it has become the equal to MC square,
a formula that actually mathematicians
can look at and understand.
That's a simple formula you might say.
So, let me copy and paste much more real world example.
There, I just pasted a much more interesting formula,
and you have the right mathematical notation
for it appearing on the right hand side.
Let me switch over
to a different Wiki that I had created sometime back.
I'll show you the power of
what Markdown and embedded STML that we support can do.
You can create pages like this,
or like this using the power
of Markdown and STML in VSTS Wiki.
So one thing inherent to Wiki is ordering of pages,
and hierarchy of pages.
That's very simple to do in VSTS Wiki.
I can click on a page,
and quickly create a sub page,
and save it, and as you can see,
I have sub pages now within Azure Active Directory.
I can move this page around to become
a sub page of somebody else, as you see.
The other problem that comes around with moving pages,
is that links get broken very easily.
So, I'll dismiss this dialog,
but when you're moving around pages in a Wiki
and the pages are interlinked with each other,
it's very easy to have broken links where a preference
of a link has been broken because the page has moved.
So, now what VSTS Wiki allows you to do,
is if I move this page or were
to say being a sub page of VSTS home,
it allows you to check for
effective links on the rest of the pages,
and brings out not just page links
that might be broken with your move,
but also Workitems links
that will get broken with your move,
and instead of you having to go fix it,
it actually fixes it for you,
and then moves the page.
So, all I have to say is fix and move,
and now VSTS Wiki is going off fixing the pages,
and then making my page a sub page of the Wiki homepage.
So, while John was working on the VSTS Wiki UI, Jessica,
who is our co-developer,
like I said doesn't want to work in the UI,
she want to work in the ID.
Here, Jessica could see the URL of the Wiki,
and actually clone it to her desktop take it off line and
work on Wiki pages like she would work on any code file,
and come back and create
a pull request for the Wiki documentation.
As simple as that. So, we cater to
both John's persona, and Jessica's persona.
However, when we interviewed personas like Jessica,
we realized that it's not
just the need to take Wiki pages offline,
Jessica already has a bunch of documentation
stored in the code repository alongside her actual code.
This is API level documentation,
is the key level documentation,
that she has been writing for a long time.
But there are four problems that these personas run into.
Number one, anybody who
wants to read their documentation,
actually has to sift through all the code,
and find the documentation.
Number two, if the product has multiple versions,
the documentation is very hard to maintain.
Number three, there is
no ordering of files in a GIT repository,
and Wiki is inherently built on ordering.
Number four, there is no easy way to discover
the pages and the documentation that have
been written in a code repository.
So let's see how VSTS Wiki addresses these four problems.
I'll go back to
the original project that we were working in,
and I'll go to "code",
and as you can see there's been
some code which is being written,
and what I know is,
there are also Product level documentation
that is residing alongside the code.
So, to publish this documentation to Wiki,
I'll go to Wiki, and click on "
Publish code as Wiki." That's it.
You've select the repo from which you
want the documentation to be picked up,
the branch, the folder,
which is docs ref conceptual,
and we enter our Wiki name, and click "publish".
That's it. What is happening now is,
we are actually going through
the folder and the sub folder specified by you,
finding all the Markdown files,
and creating a Wiki for you from those pages.
Now, that doesn't mean that we copied
these pages all into a Wiki,
these are pages which are
still residing in that code repo,
but have become so much easier to now
read and go through for anybody who
is trying to find documentation for the code.
Now, we talked about versions.
Assume that this product also had a version 0.7,
that had shape sometime back,
and very similar to
the way the documentation was written down,
it was also written for that version.
VSTS Wiki makes it very simple now to
publish multiple versions of
documentation for the same product.
All I have to do is to click "Publish
new version," point to
the branch that has
the version that has
a documentation, and click " Update."
Done. Anybody who now lands on this page
can see that there are two versions of this product,
or and this documentation,
master and version 0.7, and choose accordingly.
The third problem as we talked about,
is ordering of files.
In GIT repositories, there
is no inherent ordering of files,
and so, the Wiki is just a flat structure
of pages that you have on the GIT repository.
However, you can change that in VSTS Wiki.
Let me go back to docs ref conceptual,
and add a file here called.order.
This is the file that VSTS Wiki uses to maintain
the hierarchy and ordering of pages on the Wiki site.
So, here, let's assume that we just want
node SDK Azure install
to be the first page that shows up.
I will come at this, and done.
Now, when I go back to Wiki,
to version seven, as
you can see the Node SDK Azure install
is the first page that shows up.
The last thing I want to talk about is Discovery.
Documentation is useless if
nobody else can find it and see it.
So, here using the search box on the top,
you can find the documentation
that you just publish from code repository or to Wiki.
So, if I search for Azure Node,
you'll see all the pages that have Azure Node in them,
regardless of whether it's in the title or
in the actual body of the page,
and makes the Wiki pages much more discoverable,
and therefore, helps people
find what they're looking for.
So, going back to our dec, in summary,
VSTS Wiki allows you to create, project, process,
or develop documentation in
a very easy and simplified manner.
It supports Markdown, uses the power of GIT,
and enables you to have
Ubiquities discovery of all your Wiki pages.
If you want to know more about VST Wiki,
go to aka.ms/devopswiki,
and feel free to contact us,
either me or Sandeep,
anytime you have questions or feedback on
VSTS Wiki. Thank you so much.